heyquilt 0.0.1 → 0.3.90

package/src/duties.js

@@ -0,0 +1,303 @@
+// What an agent owes the people it works with, and what it should know before it acts,
+// whatever tool it runs in. Pure checks shared by the local MCP, the hosted MCP and the
+// Claude Code hooks, so every agent gets the same rules:
+//
+// - before editing a file: who holds it (claims are what keep agents off each other's
+//   files), and what was said about it in chat lately, as context;
+// - before moving work on (claims, tasks, commits, "done"): every direct message and
+//   mention is answered (a message back to that person, or to everyone, after theirs);
+// - before finishing or letting go of a file: anyone waiting for it in its file queue is
+//   handed it, with the holder's context (quilt_handoff). A file someone else holds is
+//   asked for in its queue (quilt_request_file), not taken.
+//
+// Chat never blocks a file: Quilt can't tell "don't touch it" from "is it done?". A file
+// is held by a claim; a message about it is something the agent reads.
+//
+// Messages are chat entries ({ id, by, to, text, ts }) the reader can see.
+import { mentionsMe, mentioned, ALL_AGENTS } from './inbox.js'
+import { RELAY_BY } from './branches.js'
+import { RELAY_OLD_NAMES } from './ui/chat.js'
+
+
+// How far back chat about a file is still worth reading before editing it.
+export const REQUEST_WINDOW_MS = 24 * 60 * 60 * 1000
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/**
+ * Does `text` name `rel`? The whole path counts, and so does a file name with an
+ * extension (app.js), as its own word: "src/app.js", "`app.js`" and "app.js?" do,
+ * "myapp.js" and "app.json" don't.
+ */
+export function namesPath (text, rel) {
+  const t = String(text || '')
+  const p = String(rel || '').replace(/^\.\//, '')
+  if (!t || !p) return false
+  const base = p.split('/').pop()
+  const tokens = [p]
+  if (base !== p && /\.\w/.test(base)) tokens.push(base)
+  return tokens.some((tok) => new RegExp(`(^|[^\\w.-])${escapeRe(tok)}(?![\\w-]|\\.\\w)`, 'u').test(t))
+}
+
+const ANY_MENTION = /(^|[^\w@])@\w/u
+
+/**
+ * Did `me` write back to `who` after `ts`? A direct message to them, a message that @mentions
+ * them, or one to everyone that mentions nobody. A message @mentioning only others is not an answer.
+ */
+export function answered (messages, me, who, ts) {
+  const mine = Array.isArray(me) ? me : [me] // an AI session answers under any name it has had
+  return (messages || []).some((m) => m && mine.includes(m.by) && (m.ts || 0) > (ts || 0) &&
+    (m.to ? m.to === who : mentioned(m.text, [who]).length > 0 || !ANY_MENTION.test(String(m.text || ''))))
+}
+
+// ------------------------------------------------------------------ chat --
+// Every message says who it is for, so only they are woken: @Name in the text (several are
+// fine), or a direct message. Several AI sessions can work as one member at once (a person
+// with Claude Code in one window and Cursor in another); they see the same messages, so only
+// one of them answers each person: the others are refused a repeat.
+
+/** How to use chat, said by quilt_message (local and hosted) and in every agent's instructions. */
+export const CHAT_RULES = 'Send a chat message. Start it with @Name of each person or agent it is for (several are fine; @Agents for every agent): ' +
+  'only they are told, so nobody else is interrupted. A message that names nobody is refused unless it is a real announcement (everyone: true). ' +
+  'Write only when you have something they need: an answer, a question, a handoff, a warning. Never send greetings, welcomes, thanks or "noted" replies. ' +
+  '@Quilt answers questions about the session itself (who is connected, which branches it keeps, how they stand against git) as a direct message to you. ' +
+  'Other AI sessions may be working as the same member as you (other windows, other tools) and see the same messages: only one answers each person, and Quilt refuses a repeat. ' +
+  'A direct message you answer gets its id on your reply (re), and each message is answered once: Quilt refuses a second answer to the same one.'
+
+/** What quilt_message's `re` is for, local and hosted. */
+export const RE_HELP = 'Id of the message you are answering (the id in your inbox). It goes back to its sender. Without it, a direct message answers the latest one they sent you. A message already answered is refused'
+
+/** Who a message is for: `to`, or the names among `names` (and @Agents, and @Quilt) it mentions. */
+export function addressees (text, to, names) {
+  return to ? [String(to)] : mentioned(text, [...new Set([...(names || []), ALL_AGENTS, RELAY_BY, ...RELAY_OLD_NAMES])])
+}
+
+/** Why a message may not go as it is: it names nobody (no `to`, no @Name), so it is for no one in particular. '' when fine. */
+export function unaddressed (text, { to = null, everyone = false, names = [] } = {}) {
+  if (to || everyone || addressees(text, to, names).length) return ''
+  return 'Not sent: this message names nobody. Start it with @Name of each person or agent it is for ' +
+    `(${names.length ? names.slice(0, 6).map((n) => '@' + n).join(', ') : '@Name'}; @${ALL_AGENTS} for every agent): only they are told, so nobody else is interrupted. ` +
+    'Or set "to" for a direct message. If it really is an announcement for everyone, send it again with everyone: true.'
+}
+
+// How long a message from one of a member's AI sessions stands in for the others.
+export const REPEAT_WINDOW_MS = 30 * 60 * 1000
+
+/**
+ * A message one of this member's other AI sessions already sent to one of `targets`, since that
+ * person last wrote (and within the window), or null. `sent`: [{ via, targets, text, ts }] the
+ * member's AI sessions sent, oldest first; `via` is the session about to send.
+ */
+export function sentByAnother (sent, { via, targets = [], messages = [], now = Date.now(), windowMs = REPEAT_WINDOW_MS } = {}) {
+  if (!via) return null
+  for (const t of targets) {
+    const lastFrom = (messages || []).reduce((n, m) => m && m.by === t && (m.ts || 0) > n ? m.ts : n, 0)
+    for (let i = (sent || []).length - 1; i >= 0; i--) {
+      const s = sent[i]
+      if (!s || s.via === via || s.ts <= lastFrom || s.ts < now - windowMs) continue
+      if ((s.targets || []).includes(t)) return { to: t, text: s.text, ts: s.ts }
+    }
+  }
+  return null
+}
+
+/** Why a repeat is refused: what the other session already said. */
+export function renderRepeat (hit, now = Date.now()) {
+  return `Not sent: another AI session working as you already wrote to ${hit.to} ${ago(hit.ts, now)}: "${quote(hit.text)}". ` +
+    `${hit.to} has that, and has not written since, so do not repeat it, thank them or greet them again. ` +
+    'If yours is about something different that they need from you, send it again with also: true.'
+}
+
+// ------------------------------------------------------------- reply ids --
+// A direct message that answers one carries its id (`re`), so an AI can see a message was
+// already answered (by it, or by another of its person's AI sessions) and not answer twice.
+
+/**
+ * The reply id for a message about to go out, and whether it is a second answer to the same
+ * message. `names`: every name the sender answers to (its own, its person's, their other AI
+ * sessions'). `re`: the id it says it answers ('' to work it out: the latest direct message
+ * from `to` to one of `names`). Returns { to, re, repeat } where `repeat` ({ re, to, text, ts }:
+ * the earlier answer) is set when that message was already answered and its sender has not
+ * written since, or { error } for an id that can't be answered.
+ */
+export function replyFor (messages, { names = [], to = null, re = '', now = Date.now(), windowMs = REPEAT_WINDOW_MS } = {}) {
+  const list = (messages || []).filter((m) => m && typeof m.id === 'string')
+  const ours = (m) => names.includes(m.by)
+  let orig = null
+  if (re) {
+    orig = list.find((m) => m.id === re)
+    if (!orig) return { error: `No message with id ${re}: check the id in your inbox.` }
+    if (ours(orig)) return { error: `Message ${re} is your own: give the id of the message you are answering.` }
+    if (!to && orig.to) to = orig.by // answering a direct message answers its sender
+  } else if (to) {
+    for (let i = list.length - 1; i >= 0 && !orig; i--) if (list[i].by === to && names.includes(list[i].to)) orig = list[i]
+  }
+  if (!orig) return { to, re: '', repeat: null }
+  const earlier = list.filter((m) => ours(m) && m.re === orig.id).pop()
+  if (earlier) {
+    const lastFrom = list.reduce((n, m) => m.by === orig.by && (m.ts || 0) > n ? m.ts : n, 0)
+    // Explicitly answered twice, or written to again right after answering with nothing new from them.
+    if (re || ((earlier.ts || 0) >= lastFrom && (earlier.ts || 0) > now - windowMs)) {
+      return { to, re: orig.id, repeat: { re: orig.id, to: orig.by, text: earlier.text, ts: earlier.ts } }
+    }
+    return { to, re: '', repeat: null } // a new message to them, not an answer to that one
+  }
+  return { to, re: orig.id, repeat: null }
+}
+
+/** Why a second answer to one message is refused: the answer already sent. */
+export function renderReplied (hit, now = Date.now()) {
+  return `Not sent: ${hit.to}'s message ${hit.re} was already answered ${ago(hit.ts, now)}: "${quote(hit.text)}". ` +
+    `${hit.to} has not written since, so do not answer it again, thank them or confirm. ` +
+    'If yours is something new that they need from you, send it again with also: true.'
+}
+
+/**
+ * Recent chat from others that names one of `paths`: what people said about the files this
+ * agent is about to change (asked for, warned off, planned). Each is
+ * { path, id, by, to, text, ts, answered }, oldest first; `answered` is whether `me` wrote
+ * back to that person (or everyone) since.
+ */
+export function chatAbout (paths, { messages = [], me, now = Date.now(), windowMs = REQUEST_WINDOW_MS } = {}) {
+  const out = []
+  for (const m of messages) {
+    if (!m || !m.by || m.by === me || typeof m.text !== 'string') continue
+    if (m.to && m.to !== me) continue
+    if ((m.ts || 0) < now - windowMs) continue
+    const hit = (paths || []).find((p) => namesPath(m.text, p))
+    if (!hit) continue
+    out.push({ path: hit, id: m.id, by: m.by, to: m.to || null, text: m.text, ts: m.ts, answered: answered(messages, me, m.by, m.ts) })
+  }
+  return out
+}
+
+// Words a message made only of pleasantries is built from: a goodnight, a greeting, thanks, an
+// "ok". Such a message asks nothing, so nobody has to answer it before they go on working.
+const PLEASANTRY = new Set(('goodnight night nite gn bye goodbye cya later morning gm evening afternoon hi hello hey heya yo ' +
+  'thanks thank thx ty cheers appreciated appreciate ok okay k kk alright allright cool nice great awesome perfect noted sweet ' +
+  'bed bedtime sleep welcome np lol haha').split(' '))
+const FILLER = new Set(('good have a an the all everyone everybody guys folks team yall you u ya see for now today tonight time day ' +
+  'very much so and it got sounds off signing heading out im i am going to soon tomorrow again one well there oh wow agents agent ' +
+  'is its that this me we are too also just really done my your').split(' '))
+
+/**
+ * Whether a message plainly needs nothing back: after its @mentions, only a few words of
+ * goodnight, greeting, thanks or "ok", with no question ("alright, bed time. Goodnight @Agents").
+ * Anything else, or anything in doubt, still waits for an answer.
+ */
+export function needsNoReply (text) {
+  const t = String(text || '')
+  if (t.includes('?')) return false
+  const words = t.replace(/(^|\s)@\S+/gu, ' ').toLowerCase().replace(/['’]/g, '').split(/[^\p{L}\p{N}]+/u).filter(Boolean)
+  if (!words.length || words.length > 14) return false
+  return words.every((w) => PLEASANTRY.has(w) || FILLER.has(w)) && words.some((w) => PLEASANTRY.has(w))
+}
+
+/**
+ * Straight from the chat: direct messages to `me` and mentions of `me` (recent, from others)
+ * with no later message from `me` to that person or everyone, as inbox-like events.
+ * `agent`: `me` joined as an agent, so an @Agents message waits on it too.
+ */
+export function waitingOn (messages, me, { now = Date.now(), windowMs = REQUEST_WINDOW_MS, agent = false, settled = null } = {}) {
+  const out = []
+  const names = Array.isArray(me) ? me : [me] // an AI session's name, and the ones it had before
+  for (const m of messages || []) {
+    if (!m || !m.by || names.includes(m.by) || typeof m.text !== 'string' || (m.ts || 0) < now - windowMs) continue
+    if (settled && settled.has(m.id)) continue // needs no reply (quilt_inbox no_reply)
+    if (fileQueueMessage(m)) continue // a file queue request or a handoff: handled by handing off, not by a reply
+    if (m.kind === 'commit') continue // a commit request told to the owner: handled by committing (quilt_commit_request_done)
+    if (needsNoReply(m.text)) continue // a goodnight, a greeting, thanks: asks nothing
+    const kind = names.includes(m.to) ? 'dm' : !m.to && names.some((n) => mentionsMe(m.text, n, { agent })) ? 'mention' : null
+    if (kind && !answered(messages, names, m.by, m.ts)) out.push({ id: m.id, kind, by: m.by, text: m.text, ts: m.ts })
+  }
+  return out
+}
+
+/**
+ * A message that needs no reply: one the relay wrote for the file queue (someone asking for a file,
+ * or a file handed over), or a note that work someone asked to commit was committed (commit.js).
+ */
+export const fileQueueMessage = (m) => !!m && (m.kind === 'queue' || m.kind === 'handoff' || m.kind === 'commit' || m.kind === 'nudge')
+
+/** Direct messages and mentions among inbox `events` that `me` has not answered yet. */
+export function unanswered (events, { messages = [], me } = {}) {
+  return (events || []).filter((e) => e && (e.kind === 'dm' || e.kind === 'mention') && !e.queue && !e.commit && !e.nudge && e.by !== me && !needsNoReply(e.text) && !answered(messages, me, e.by, e.ts))
+}
+
+/**
+ * Files `me` holds that someone is waiting for: [{ pattern, queue: [{ id, path, by, title,
+ * description, task }] }], from the relay's claim list.
+ */
+export function queuedFor (claims, me) {
+  return (claims || []).filter((c) => c && c.by === me && Array.isArray(c.queue) && c.queue.length).map((c) => ({ pattern: c.pattern, queue: c.queue }))
+}
+
+const requestLine = (r) => `${r.by}${r.path ? ` (for ${r.path})` : ''}: "${quote(r.title)}"${r.description ? ` — ${quote(r.description)}` : ''}${r.task ? ` (task ${r.task})` : ''}`
+
+/** Who is waiting for the files `me` holds, as lines an agent reads with every answer; '' when nobody is. */
+export function renderQueueNotice (held) {
+  if (!held || !held.length) return ''
+  const lines = held.map((h) => `- ${h.pattern}: ${h.queue.map(requestLine).join('; then ')}`)
+  return 'Waiting in the file queue for files you hold:\n' + lines.join('\n') + '\n' +
+    'Finish the change you are making to each, then hand it off with quilt_handoff (path, and context: what you changed, what is left, anything they should know). ' +
+    'You cannot finish or release these files until you do.'
+}
+
+/** Why an agent may not finish (or let go of files) yet: files it holds that someone is waiting for. '' when none. */
+export function renderQueued (held, then = 'finish again') {
+  if (!held || !held.length) return ''
+  return 'Not yet: ' + renderQueueNotice(held).replace(/^Waiting/, 'people are waiting') + ` Then ${then}.`
+}
+
+const quote = (t) => {
+  const s = String(t || '').replace(/\s+/g, ' ').trim()
+  return s.length > 300 ? s.slice(0, 300) + '…' : s
+}
+
+const ago = (ts, now) => {
+  const m = Math.max(0, Math.round((now - (ts || now)) / 60000))
+  return m < 1 ? 'just now' : m < 60 ? `${m}m ago` : `${Math.round(m / 60)}h ago`
+}
+
+/** What was said about the files an agent is about to change, newest last, or '' when nothing was. */
+export function renderChatAbout (said, { now = Date.now(), max = 8 } = {}) {
+  if (!said || !said.length) return ''
+  const shown = said.slice(-max)
+  const lines = shown.map((r) => `- ${r.by}${r.to ? ' (to you)' : ''}, ${ago(r.ts, now)}, about ${r.path}: "${quote(r.text)}"${r.answered ? '' : ' (you have not replied)'}`)
+  const more = said.length > shown.length ? `\n(and ${said.length - shown.length} earlier: quilt_read_messages)` : ''
+  return 'What people said in chat about these files:\n' + lines.join('\n') + more + '\n' +
+    'Take it into account: if they asked you to leave a file alone or to change it a certain way, do that, and reply to anyone you have not replied to with quilt_message.'
+}
+
+/**
+ * Why an agent may not go on yet: the messages it still owes an answer, or '' when it owes none.
+ * `then` says what to do once they're answered ("finish again", "call quilt_claim again").
+ */
+export function renderUnanswered (events, then = 'finish again') {
+  if (!events || !events.length) return ''
+  const lines = events.map((e) => `- ${e.by} ${e.kind === 'dm' ? 'sent you a direct message' : 'mentioned you'}${e.id ? ` (id ${e.id})` : ''}: "${quote(e.text)}"`)
+  return 'Not yet: these people are still waiting for an answer from you:\n' + lines.join('\n') + '\n' +
+    `Answer each that asks something of you with quilt_message (to: their name), even if only to say when you will get to it. ` +
+    `One that needs nothing back (thanks, a greeting, an FYI, a status report) gets no reply: settle it with quilt_inbox (no_reply: [its id]). Then ${then}. ` +
+    'Reading, messaging and checking files work meanwhile.'
+}
+
+/** One refusal for an edit to a file someone else holds: who, and what to do instead of retrying. */
+export function heldRefusal (rel, claim, error) {
+  const holder = claim ? claim.by : 'someone else'
+  const why = claim ? (claim.note ? ` (${claim.note})` : '') : error ? ` (${error})` : ''
+  // A box (docs/superpowers/specs/2026-10-16-git-boxes-design.md): their work isn't in this folder yet.
+  if (claim && claim.box) return `${rel} is boxed by ${holder}${why}: their unfinished work, which isn't in your folder until they commit or unpack it. Quilt refuses edits to it and would undo them. ${askForIt(rel, claim)}`
+  const covered = claim && claim.pattern && claim.pattern !== rel ? `, as part of their claim on ${claim.pattern}` : ''
+  return `${rel} is claimed by ${holder}${why}${covered}, so Quilt refuses edits to it and would undo them. ${askForIt(rel, claim)}`
+}
+
+/** What to do about a file someone else holds: ask for it in its file queue, and carry on. */
+export function askForIt (rel, claim) {
+  const holder = claim ? claim.by : 'its holder'
+  const waiting = claim && Array.isArray(claim.queue) && claim.queue.length ? ` ${claim.queue.length} already waiting for it.` : ''
+  return `Do not retry or work around it.${waiting} ` +
+    `Ask for it in its file queue with quilt_request_file (path "${rel}", a title like "Working on <what> for <task>", and a description of up to 300 characters: what you plan to change and why). ` +
+    `${holder} is told, and hands it to you with their context when they are done; you are woken when it is yours. Carry on with other work meanwhile.`
+}

package/src/editors.js

@@ -0,0 +1,228 @@
+// Opens a session's folder in the AI coding app someone already has
+// installed (Claude, Cursor, Codex...), so their AI works right where the
+// files sync and its chats reach the session's feed.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { execFile, execFileSync, spawn } from 'node:child_process'
+
+// `tool` matches the AI tool names people pick in their profile. On a Mac,
+// `mac` is the app bundle; `url` builds a link the app opens instead of the
+// folder being handed to it; `cli` is the app's own command-line launcher
+// inside the bundle, run with `args` before the folder. On Windows, `win` is
+// the exe under %LOCALAPPDATA%. `winCli` is that install's command-line
+// launcher, relative to the exe; opening through it (see openCommand) brings
+// the window forward when the app is already running. `macMore` is another
+// bundle the app may ship as, counted only when its bundle id matches.
+export const EDITORS = [
+  // The Claude app's own "new session in this folder" link loses the folder
+  // once you type, so a session is made in the folder first (see openInClaude)
+  // and the app opens that; the link is only the fallback. With a prompt (a
+  // merge to settle) the fallback link fills it into the new chat's input as `q`.
+  // On Windows the Store build is found by its package folder or the claude://
+  // link it registers. The versioned WindowsApps path changes on every update.
+  { id: 'claude', name: 'Claude Code', tool: 'Claude Code', mac: 'Claude', win: 'AnthropicClaude/claude.exe', winMore: ['Programs/Claude/Claude.exe'], winPackage: 'Claude_pzs8sxrjxfjjc', protocol: 'claude', url: (dir, prompt) => `claude://code/new?folder=${encodeURIComponent(dir)}${prompt ? `&q=${encodeURIComponent(prompt)}` : ''}` },
+  // Cursor otherwise opens its Agents window, whose chats stay on whatever
+  // project was used last; a classic window ties the agent to this folder.
+  { id: 'cursor', name: 'Cursor', tool: 'Cursor', mac: 'Cursor', cli: 'Contents/Resources/app/bin/cursor', args: ['--classic', '--new-window'], win: 'Programs/cursor/Cursor.exe', winCli: 'resources/app/bin/cursor.cmd' },
+  // The Codex app now ships as ChatGPT.app; only the build with Codex's bundle id counts,
+  // not the older chat-only ChatGPT app. It opens a folder handed to it as a project.
+  { id: 'codex', name: 'Codex', tool: 'Codex', mac: 'Codex', macMore: [{ app: 'ChatGPT', bundleId: 'com.openai.codex' }] },
+  { id: 'windsurf', name: 'Windsurf', tool: 'Windsurf', mac: 'Windsurf', win: 'Programs/Windsurf/Windsurf.exe' },
+  { id: 'vscode', name: 'VS Code', tool: 'GitHub Copilot', mac: 'Visual Studio Code', win: 'Programs/Microsoft VS Code/Code.exe' },
+  { id: 'zed', name: 'Zed', tool: 'Zed', mac: 'Zed' }
+]
+
+// Paths in `platform`'s style, so a Mac layout reads the same when tests run on Windows.
+const pathsOf = (platform) => platform === 'win32' ? path.win32 : path.posix
+
+/** Where an editor is installed on this computer, or null. */
+function locate (ed, opts = {}) {
+  const { platform = process.platform, home = os.homedir(), exists = fs.existsSync, localAppData = process.env.LOCALAPPDATA, bundleIdOf = macBundleId } = opts
+  const path = pathsOf(platform)
+  if (platform === 'darwin') {
+    const dirs = ['/Applications', path.join(home, 'Applications')]
+    for (const dir of dirs) {
+      const app = path.join(dir, `${ed.mac}.app`)
+      if (ed.mac && exists(app)) return app
+    }
+    for (const more of ed.macMore || []) {
+      for (const dir of dirs) {
+        const app = path.join(dir, `${more.app}.app`)
+        if (exists(app) && bundleIdOf(app) === more.bundleId) return app
+      }
+    }
+    return null
+  }
+  if (platform === 'win32') {
+    const local = localAppData || path.join(home, 'AppData', 'Local')
+    const candidates = [
+      ...(ed.win ? [ed.win] : []),
+      ...(ed.winMore || []),
+      ...(ed.winPackage ? [`Packages/${ed.winPackage}`] : [])
+    ]
+    for (const rel of candidates) {
+      const found = path.join(local, ...rel.split('/'))
+      if (exists(found)) return found
+    }
+    if (ed.protocol && hasProtocol(ed.protocol, opts)) return `${ed.protocol}://`
+    return null
+  }
+  return null
+}
+
+/** A Mac app's bundle id, from its Info.plist, or null. */
+function macBundleId (app) {
+  try {
+    const plist = fs.readFileSync(path.join(app, 'Contents', 'Info.plist'), 'utf8')
+    return plist.match(/<key>CFBundleIdentifier<\/key>\s*<string>([^<]+)<\/string>/)?.[1] || null
+  } catch { return null }
+}
+
+/** Whether `name://` is a registered link on this computer. `protocols` is for tests. */
+function hasProtocol (name, { protocols, query = execFileSync } = {}) {
+  if (protocols) return protocols(name)
+  if (process.platform !== 'win32') return false
+  try {
+    query('reg', ['query', `HKCU\\Software\\Classes\\${name}`, '/v', 'URL Protocol'], { windowsHide: true, stdio: 'ignore', timeout: 3000 })
+    return true
+  } catch { return false }
+}
+
+/** The editors installed here, in list order: [{ id, name, tool }]. */
+export function installedEditors (opts) {
+  return EDITORS.filter((ed) => locate(ed, opts)).map(({ id, name, tool }) => ({ id, name, tool }))
+}
+
+/** The command that opens `dir` in editor `id`: [file, args, runOpts?]. */
+export function openCommand (id, dir, opts = {}) {
+  const ed = EDITORS.find((e) => e.id === id)
+  if (!ed) throw new Error('Unknown app.')
+  const where = locate(ed, opts)
+  if (!where) throw new Error(`${ed.name} isn't installed on this computer.`)
+  const platform = opts.platform || process.platform
+  const path = pathsOf(platform)
+  const args = ed.args || []
+  if (platform === 'darwin') {
+    if (ed.url) return ['open', [ed.url(dir, opts.prompt)]]
+    if (ed.cli) return [path.join(where, ...ed.cli.split('/')), [...args, dir]]
+    return ['open', ['-a', where, dir]]
+  }
+  // An encoded link has no spaces or quotes, so it reaches cmd unquoted: its & must be escaped.
+  if (ed.url) return ['cmd', ['/c', 'start', '""', ed.url(dir, opts.prompt).replaceAll('&', '^&')]]
+  // Launching Cursor.exe while it is already open hands the folder to the
+  // running instance and leaves that window behind whatever is in front.
+  // `start` of its CLI activates the window on the folder instead.
+  if (ed.winCli) {
+    const cli = path.join(path.dirname(where), ...ed.winCli.split('/'))
+    const exists = opts.exists || fs.existsSync
+    if (exists(cli)) return ['cmd.exe', ['/c', 'start', '', cli, ...args, dir], { activate: true }]
+  }
+  return [where, [...args, dir]]
+}
+
+const run = (file, args, opts = {}) => {
+  // `start` returns as soon as the app is activated; waiting would hold the
+  // button until the launcher's console exits.
+  if (opts.activate) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(file, args, { detached: true, stdio: 'ignore', windowsHide: false })
+      child.once('error', reject)
+      child.once('spawn', () => { child.unref(); resolve() })
+    })
+  }
+  return new Promise((resolve, reject) => {
+    const child = execFile(file, args, { windowsHide: true, timeout: 60000, ...opts }, (err, stdout, stderr) => {
+      if (!err) return resolve()
+      // What the tool said beats "Command failed: <the whole prompt>".
+      const said = `${stderr || ''}\n${stdout || ''}`.split('\n').map((l) => l.trim()).find(Boolean)
+      if (err.killed) err.message = 'timed out'
+      else if (said) err.message = said.slice(0, 300)
+      reject(err)
+    })
+    child.stdin?.end() // the Claude CLI waits for stdin to close before running a prompt
+  })
+}
+
+/** The Claude Code command-line tool: installed on its own, or the copy inside the Claude app. */
+export function claudeCli ({ platform = process.platform, home = os.homedir(), exists = fs.existsSync, readdir = fs.readdirSync } = {}) {
+  const exe = platform === 'win32' ? 'claude.exe' : 'claude'
+  // PATH is this computer's, whatever platform is asked about.
+  const delimiter = pathsOf(process.platform).delimiter
+  const path = pathsOf(platform)
+  const dirs = [path.join(home, '.local', 'bin'), path.join(home, '.claude', 'local'), '/opt/homebrew/bin', '/usr/local/bin',
+    ...(process.env.PATH || '').split(delimiter).filter(Boolean)]
+  for (const d of dirs) if (exists(path.join(d, exe))) return path.join(d, exe)
+  if (platform === 'darwin') {
+    const bundled = path.join(home, 'Library', 'Application Support', 'Claude', 'claude-code')
+    let versions = []
+    try { versions = readdir(bundled) } catch {}
+    versions.sort((a, b) => b.localeCompare(a, undefined, { numeric: true }))
+    for (const v of versions) {
+      const cli = path.join(bundled, v, 'claude.app', 'Contents', 'MacOS', 'claude')
+      if (exists(cli)) return cli
+    }
+  }
+  return null
+}
+
+/** How a new Claude Code session named after the folder is made, without a model call. */
+export function claudeSessionCommand (cli, dir, id) {
+  return [cli, ['-p', `/rename ${path.basename(dir)} (quilt)`, '--session-id', id], { cwd: dir }]
+}
+
+/** Puts text on the clipboard (pbcopy on a Mac, clip on Windows, xclip elsewhere). False when it couldn't. */
+export async function copyToClipboard (text) {
+  const cmd = process.platform === 'darwin' ? ['pbcopy', []] : process.platform === 'win32' ? ['clip', []] : ['xclip', ['-selection', 'clipboard']]
+  return new Promise((resolve) => {
+    const child = spawn(cmd[0], cmd[1], { stdio: ['pipe', 'ignore', 'ignore'] })
+    child.on('error', () => resolve(false))
+    child.on('close', (code) => resolve(code === 0))
+    child.stdin.end(text)
+  })
+}
+
+const resumeLink = (id, platform = process.platform) => (platform === 'win32' ?['cmd', ['/c', 'start', '""', `claude://resume?session=${id}`]] : ['open', [`claude://resume?session=${id}`]])
+
+async function openInClaude (dir, opts) {
+  const runFn = opts.run || run
+  const copyFn = opts.copy || copyToClipboard
+  const [file, args] = openCommand('claude', dir, opts) // checks it's installed; the folder link is the fallback
+  const cli = claudeCli(opts)
+  // The folder link (with a prompt, filled into the new chat and on the clipboard too) — everything else falls back to this.
+  // That chat can lose its folder once it is sent, so it is only the fallback.
+  const fallback = async () => {
+    const copied = opts.prompt ? await copyFn(opts.prompt) : false
+    await runFn(file, args)
+    return copied
+  }
+  // A chat made in the folder keeps it. The app can't fill a prompt into one it opens this way,
+  // so a merge's prompt goes on the clipboard: Quilt never runs an AI itself.
+  if (cli) {
+    const id = crypto.randomUUID()
+    try {
+      await runFn(...claudeSessionCommand(cli, dir, id))
+      const copied = opts.prompt ? await copyFn(opts.prompt) : false
+      await runFn(...resumeLink(id, opts.platform))
+      return { copied }
+    } catch {} // fall back to the folder link
+  }
+  const copied = await fallback()
+  return opts.prompt ? { copied, filled: true } : { copied }
+}
+
+export async function openIn (id, dir, opts = {}) {
+  dir = pathsOf(opts.platform || process.platform).resolve(dir) // in `platform`'s style, as locate() reads it
+  try {
+    if (id === 'claude') return await openInClaude(dir, opts)
+    const runFn = opts.run || run
+    const copyFn = opts.copy || copyToClipboard
+    const command = openCommand(id, dir, opts) // throws for an unknown or missing app: the clipboard is left alone
+    const copied = opts.prompt ? await copyFn(opts.prompt) : false
+    await runFn(...command)
+    return { copied }
+  } catch (err) {
+    throw new Error(`Could not open it: ${err.message}`)
+  }
+}

package/src/fsutil.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { makeIgnore, isIgnored, scopeIgnore, IGNORE_FILES } from './pathrules.js'
+
+export { IGNORE_FILES } from './pathrules.js'
+export { MAX_TEXT_BYTES, MAX_BINARY_BYTES, LARGE_FILE_BYTES, MAX_STORED_BINARY_BYTES, isIgnored, isSafeRelPath, globMatcher, patternsOverlap } from './pathrules.js'
+
+export function toPosix (p) {
+  return p.split(path.sep).join('/')
+}
+
+/**
+ * Builds the ignore matcher from built-ins and every .gitignore / .quiltignore
+ * in the project, each applying to its own folder. Folders already ignored
+ * aren't searched, so a .gitignore inside node_modules has no say.
+ */
+export function loadIgnore (root) {
+  const ig = makeIgnore()
+  const visit = (dirRel) => {
+    const dir = path.join(root, dirRel)
+    for (const file of IGNORE_FILES) {
+      try { ig.add(scopeIgnore(fs.readFileSync(path.join(dir, file), 'utf8'), dirRel)) } catch {}
+    }
+    let entries
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      const rel = dirRel ? `${dirRel}/${e.name}` : e.name
+      if (!isIgnored(ig, rel)) visit(rel)
+    }
+  }
+  visit('')
+  return ig
+}
+
+/**
+ * Resolves a relative path to an absolute one inside root, making sure no
+ * symlinked parent directory points outside of it (or nowhere: a dangling
+ * link could later lead anywhere). Throws when it does; the path is then
+ * neither read nor written.
+ */
+export function resolveInside (root, rel) {
+  const parts = rel.split('/')
+  const abs = path.join(root, ...parts)
+  const realRoot = fs.realpathSync(root)
+  const refuse = () => { throw new Error(`refusing to touch a path outside the project: ${rel}`) }
+  let dir = root
+  for (const part of parts.slice(0, -1)) {
+    dir = path.join(dir, part)
+    let st
+    try { st = fs.lstatSync(dir) } catch { break } // nothing deeper exists yet
+    if (!st.isSymbolicLink()) continue
+    let real
+    try { real = fs.realpathSync(dir) } catch { refuse() }
+    if (real !== realRoot && !real.startsWith(realRoot + path.sep)) refuse()
+  }
+  return abs
+}
+
+export function looksBinary (buf) {
+  const n = Math.min(buf.length, 8000)
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true
+  // Invalid UTF-8 is treated as binary so it round-trips byte for byte.
+  return !Buffer.from(buf.toString('utf8'), 'utf8').equals(buf)
+}
+
+export function sha1 (buf) {
+  return crypto.createHash('sha1').update(buf).digest('hex')
+}
+
+/** Recursively lists syncable files as posix relative paths. */
+export function walk (root, ig) {
+  const out = []
+  const visit = (dirRel) => {
+    let entries
+    try { entries = fs.readdirSync(path.join(root, dirRel), { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      const rel = dirRel ? `${dirRel}/${e.name}` : e.name
+      if (isIgnored(ig, rel)) continue
+      if (e.isDirectory()) visit(rel)
+      else if (e.isFile()) out.push(rel)
+    }
+  }
+  visit('')
+  return out
+}