kira-glasses-bridge 2.3.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Connects your Mac to Kira, the assistant for Even G2 glasses: Claude Code sessions, files, folders and apps, by voice.",
   "type": "module",
   "bin": {

package/src/index.mjs

@@ -9,6 +9,7 @@ import { agentById, AGENTS } from './agents/index.mjs'
 import { normalizeAnswer } from './agents/protocol.mjs'
 import { openApp, installedApps } from './apps.mjs'
 import { listFiles, readUserFile, createFolder, writeUserFile, trashPath, resolveUserPath } from './files.mjs'
+import { prepareWorktree, worktreeStatus, pushWorktree, removeWorktree, repoOfFolder, stageFiles } from './worktrees.mjs'
 
 import { createRequire } from 'node:module'
 const { version: BRIDGE_VERSION } = createRequire(import.meta.url)('../package.json')
@@ -137,6 +138,28 @@ end tell`
     return new Promise(resolve => execFile('osascript', ['-e', script], err => resolve(err ? { error: err.message } : { opened: true, cwd: display(dir), command })))
   },
 
+  /** A worktree for one task attempt, off the project's checkout of the repo. */
+  prepare_worktree(args) {
+    return prepareWorktree(args)
+  },
+  worktree_status(args) {
+    return worktreeStatus(args)
+  },
+  push_worktree(args) {
+    return pushWorktree(args)
+  },
+  remove_worktree(args) {
+    return removeWorktree(args)
+  },
+  /** A task's reference files, downloaded into the worktree's .kira/files for the agent. */
+  stage_files(args) {
+    return stageFiles(args)
+  },
+  /** Which GitHub repo a folder's origin points at (project link enrichment). */
+  async repo_of_folder(args) {
+    return { repo: await repoOfFolder(args.path) }
+  },
+
   /** Read-only git facts for a folder: repo, branch, head, dirty files. */
   async git_status(args) {
     const s = await snapshot(resolveCwd(args.path ?? args.cwd))

package/src/worktrees.mjs

@@ -0,0 +1,213 @@
+// A git worktree per task attempt, so agents working on different tasks never
+// share a directory and the main checkout is never touched. Worktrees live
+// under ~/.kira/worktrees/<owner>/<repo>/<branch>; the project's linked folder
+// is only read (fetch, worktree add) and its working tree is left alone.
+import { execFile } from 'node:child_process'
+import { homedir } from 'node:os'
+import { isAbsolute, join, resolve } from 'node:path'
+import { mkdir, stat, readFile, writeFile, appendFile, rm } from 'node:fs/promises'
+import { pipeline } from 'node:stream/promises'
+import { createWriteStream } from 'node:fs'
+import { Readable } from 'node:stream'
+import { display } from './git.mjs'
+import { resolveUserPath } from './files.mjs'
+
+const ROOT = join(homedir(), '.kira', 'worktrees')
+const SETUP_TIMEOUT_MS = 5 * 60_000
+const OUTPUT_CAP = 4000
+
+function git(cwd, args, { timeout = 60_000 } = {}) {
+  return new Promise(resolve => {
+    execFile('git', args, { cwd, maxBuffer: 16 * 1024 * 1024, timeout, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' } }, (err, stdout, stderr) => {
+      resolve({ ok: !err, out: String(stdout ?? '').trim(), err: String(stderr ?? err?.message ?? '').trim() })
+    })
+  })
+}
+
+function remoteToRepo(url) {
+  const m = /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?$/.exec(url ?? '')
+  return m ? m[1] : null
+}
+
+const sameRepo = (a, b) => !!a && !!b && a.toLowerCase() === b.toLowerCase()
+
+/** The GitHub repo a folder's origin points at, or null. */
+export async function repoOfFolder(folder) {
+  const dir = resolveUserPath(String(folder ?? ''))
+  const r = await git(dir, ['remote', 'get-url', 'origin'])
+  return r.ok ? remoteToRepo(r.out) : null
+}
+
+/** Among the project's folders, the checkout of this repo. */
+async function findCheckout(folders, repo) {
+  for (const f of folders ?? []) {
+    let dir
+    try {
+      dir = resolveUserPath(String(f))
+    } catch {
+      continue
+    }
+    const top = await git(dir, ['rev-parse', '--show-toplevel'])
+    if (!top.ok) continue
+    const origin = await git(top.out, ['remote', 'get-url', 'origin'])
+    const found = origin.ok ? remoteToRepo(origin.out) : null
+    if (sameRepo(found, repo)) return { checkout: top.out, repo: found }
+  }
+  return null
+}
+
+const exists = p => stat(p).then(() => true).catch(() => false)
+
+/**
+ * Make (or find) the worktree for a branch of a repo, based on `base`
+ * (default: the remote's default branch, else the checkout's current branch).
+ * Runs `setup_command` inside it when given (e.g. `pnpm install`), once, on
+ * creation. Idempotent: an existing worktree for the branch is returned as is.
+ */
+export async function prepareWorktree({ folders, repo, branch, base, setup_command: setupCommand }) {
+  if (!repo || !branch) return { error: 'repo and branch are required' }
+  const found = await findCheckout(folders, repo)
+  if (!found) return { error: `none of the project's folders is a checkout of ${repo}${folders?.length ? ` (looked in ${folders.map(String).join(', ')})` : ''}. Link the folder that has it.` }
+  const { checkout } = found
+  repo = found.repo // the origin's casing, so the path is the same however the repo was spelled
+
+  const path = join(ROOT, ...repo.split('/'), branch.replace(/[^\w.-]+/g, '-'))
+  if (await exists(join(path, '.git'))) {
+    const head = await git(path, ['rev-parse', 'HEAD'])
+    const mb = await git(path, ['merge-base', 'HEAD', `origin/${base || 'HEAD'}`])
+    return { path: display(path), abs: path, checkout: display(checkout), branch, existing: true, head: head.out || null, base_sha: mb.ok ? mb.out : null }
+  }
+
+  // Fresh remote refs when we can get them; offline, the local refs will do.
+  const fetched = await git(checkout, ['fetch', 'origin', '--prune', '--quiet'], { timeout: 90_000 })
+  let baseName = base
+  if (!baseName) {
+    const head = await git(checkout, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])
+    baseName = head.ok ? head.out.replace(/^origin\//, '') : (await git(checkout, ['rev-parse', '--abbrev-ref', 'HEAD'])).out || 'main'
+  }
+  const candidates = [`refs/remotes/origin/${baseName}`, `refs/heads/${baseName}`]
+  let baseRef = null
+  for (const c of candidates) if ((await git(checkout, ['rev-parse', '--verify', '--quiet', c])).ok) { baseRef = c; break }
+  if (!baseRef) return { error: `base branch ${baseName} not found in ${display(checkout)}${fetched.ok ? '' : ' (fetch failed: ' + fetched.err.split('\n').pop() + ')'}` }
+  const baseSha = (await git(checkout, ['rev-parse', baseRef])).out
+
+  await mkdir(join(path, '..'), { recursive: true })
+  const branchExists = (await git(checkout, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`])).ok
+  const add = branchExists ? await git(checkout, ['worktree', 'add', path, branch]) : await git(checkout, ['worktree', 'add', '-b', branch, path, baseRef])
+  if (!add.ok) {
+    // A stale registration (folder deleted by hand) blocks re-adding; prune once and retry.
+    await git(checkout, ['worktree', 'prune'])
+    const retry = branchExists ? await git(checkout, ['worktree', 'add', path, branch]) : await git(checkout, ['worktree', 'add', '-b', branch, path, baseRef])
+    if (!retry.ok) return { error: `git worktree add failed: ${retry.err.split('\n').pop()}` }
+  }
+  // Starting from origin/<base> makes git track it; the branch is ours, and "pushed" must mean our branch is on origin.
+  if (!branchExists) await git(path, ['branch', '--unset-upstream'])
+
+  let setup = null
+  if (setupCommand && String(setupCommand).trim()) {
+    setup = await new Promise(resolve => {
+      execFile('sh', ['-lc', String(setupCommand)], { cwd: path, timeout: SETUP_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, CI: '1' } }, (err, stdout, stderr) => {
+        const out = `${stdout ?? ''}${stderr ?? ''}`.trim()
+        resolve({ ok: !err, command: String(setupCommand), output: out.length > OUTPUT_CAP ? `…${out.slice(-OUTPUT_CAP)}` : out })
+      })
+    })
+  }
+  return { path: display(path), abs: path, checkout: display(checkout), branch, base: baseName, base_sha: baseSha, existing: false, fetched: fetched.ok, setup }
+}
+
+/** Where a worktree stands: branch, commits and files changed against its base, and whether it has been pushed. */
+export async function worktreeStatus({ path: p, base }) {
+  const path = resolveUserPath(String(p ?? ''))
+  if (!(await exists(join(path, '.git')))) return { error: 'no worktree at that path', path: display(path) }
+  const [branch, head, status] = await Promise.all([git(path, ['rev-parse', '--abbrev-ref', 'HEAD']), git(path, ['rev-parse', 'HEAD']), git(path, ['status', '--porcelain=v1'])])
+  const baseRef = base ? `origin/${base}` : 'origin/HEAD'
+  const mb = await git(path, ['merge-base', 'HEAD', baseRef])
+  const ahead = mb.ok ? await git(path, ['rev-list', '--count', `${mb.out}..HEAD`]) : { ok: false, out: '0' }
+  const diff = mb.ok ? await git(path, ['diff', '--shortstat', mb.out, 'HEAD']) : { out: '' }
+  const remoteRef = `refs/remotes/origin/${branch.out}`
+  const onOrigin = (await git(path, ['rev-parse', '--verify', '--quiet', remoteRef])).ok
+  const unpushed = onOrigin ? await git(path, ['rev-list', '--count', `${remoteRef}..HEAD`]) : null
+  const commits = mb.ok ? (await git(path, ['log', '--format=%h %s', `${mb.out}..HEAD`, '--max-count=20'])).out.split('\n').filter(Boolean) : []
+  return {
+    path: display(path),
+    branch: branch.out,
+    head: head.out.slice(0, 7),
+    dirty: status.out.split('\n').filter(Boolean).length,
+    commits_ahead: Number(ahead.out || 0),
+    commits,
+    diffstat: diff.out,
+    pushed: onOrigin && Number(unpushed?.out || 0) === 0,
+    on_origin: onOrigin,
+  }
+}
+
+/** Push the worktree's branch to origin, setting upstream. */
+export async function pushWorktree({ path: p }) {
+  const path = resolveUserPath(String(p ?? ''))
+  const branch = (await git(path, ['rev-parse', '--abbrev-ref', 'HEAD'])).out
+  if (!branch || branch === 'HEAD') return { error: 'worktree is not on a branch' }
+  const r = await git(path, ['push', '--set-upstream', 'origin', branch], { timeout: 120_000 })
+  if (!r.ok) return { error: `push failed: ${r.err.split('\n').filter(Boolean).pop()}` }
+  return { pushed: true, branch, head: (await git(path, ['rev-parse', 'HEAD'])).out.slice(0, 7) }
+}
+
+/** Remove a worktree (and optionally its branch) once its work is merged or abandoned. */
+export async function removeWorktree({ path: p, delete_branch: deleteBranch }) {
+  const path = resolveUserPath(String(p ?? ''))
+  if (!path.startsWith(ROOT + '/')) return { error: 'refusing to remove a folder outside ~/.kira/worktrees' }
+  if (!(await exists(path))) return { removed: false, note: 'already gone' }
+  const common = await git(path, ['rev-parse', '--git-common-dir'])
+  const branch = (await git(path, ['rev-parse', '--abbrev-ref', 'HEAD'])).out
+  const main = common.ok ? (isAbsolute(common.out) ? common.out : resolve(path, common.out)).replace(/\/\.git$/, '') : null
+  const r = await git(main ?? path, ['worktree', 'remove', '--force', path])
+  if (!r.ok) return { error: `worktree remove failed: ${r.err.split('\n').pop()}` }
+  let branchDeleted = false
+  if (deleteBranch && main && branch && branch !== 'HEAD') branchDeleted = (await git(main, ['branch', '-D', branch])).ok
+  return { removed: true, branch, branch_deleted: branchDeleted }
+}
+
+const STAGE_DIR = '.kira/files'
+const STAGE_MAX_BYTES = 200 * 1024 * 1024
+
+/**
+ * Put a task's reference files into the worktree under .kira/files (excluded
+ * from git through .git/info/exclude, never committed), so the agent can open
+ * them like anything else on disk. Downloads from short-lived signed URLs.
+ */
+export async function stageFiles({ path: p, files }) {
+  const path = resolveUserPath(String(p ?? ''))
+  if (!(await exists(join(path, '.git')))) return { error: 'no worktree at that path', path: display(path) }
+  const dir = join(path, STAGE_DIR)
+  await rm(dir, { recursive: true, force: true })
+  await mkdir(dir, { recursive: true })
+  // A worktree's .git is a file pointing at the real gitdir; git tells us where its exclude file lives.
+  const excl = await git(path, ['rev-parse', '--git-path', 'info/exclude'])
+  if (excl.ok) {
+    const file = isAbsolute(excl.out) ? excl.out : join(path, excl.out)
+    await mkdir(join(file, '..'), { recursive: true })
+    const current = await readFile(file, 'utf8').catch(() => '')
+    if (!current.split('\n').includes('/.kira/')) await appendFile(file, `${current && !current.endsWith('\n') ? '\n' : ''}/.kira/\n`)
+  }
+  const staged = []
+  let total = 0
+  const seen = new Set()
+  for (const f of files ?? []) {
+    let name = String(f.name ?? 'file').replace(/[\/\\]/g, '_')
+    if (seen.has(name)) name = `${name.replace(/(\.[^.]+)?$/, '')}-${seen.size}${/\.[^.]+$/.exec(name)?.[0] ?? ''}`
+    seen.add(name)
+    try {
+      const res = await fetch(String(f.url))
+      if (!res.ok || !res.body) throw new Error(`download failed (${res.status})`)
+      const len = Number(res.headers.get('content-length') ?? 0)
+      if (total + len > STAGE_MAX_BYTES) throw new Error('over the staging size limit')
+      const dest = join(dir, name)
+      await pipeline(Readable.fromWeb(res.body), createWriteStream(dest))
+      const size = (await stat(dest)).size
+      total += size
+      staged.push({ name, path: `${STAGE_DIR}/${name}`, bytes: size, description: f.description || undefined })
+    } catch (err) {
+      staged.push({ name, error: err.message })
+    }
+  }
+  return { dir: `${STAGE_DIR}/`, staged, bytes: total }
+}