heartcode 0.0.0-stage → 0.1.0

package/src/memory.js

@@ -0,0 +1,222 @@
+// Memory: markdown notes, one fact per note, linked Obsidian-style with [[name]], in two places
+// (each folder opens as an Obsidian vault):
+//   <project>/.heartcode/memory/   about this project (scope "project", the default)
+//   ~/.heart/memory/               the user's preferences that hold in every project (scope "global")
+// Each note:
+//   ---
+//   name: tabs-not-spaces
+//   description: The user wants tabs for indentation in this project
+//   type: user | project | feedback | reference
+//   tags: style, formatting
+//   ---
+//   The text. Related: [[code-style]]
+// MEMORY.md, the index for people (and Obsidian), is rebuilt by code on every change. Models get
+// less: the tag list in the system prompt, and with each message only the notes it matches.
+import fs from 'node:fs'
+import path from 'node:path'
+import { HOME } from './config.js'
+
+export const TYPES = ['user', 'project', 'feedback', 'reference']
+const LINK = /\[\[([^\]|#]+)(?:[#|][^\]]*)?\]\]/g
+export const slug = (s) =>
+  String(s)
+    .toLowerCase()
+    .replace(/\.md$/, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'note'
+
+// One folder of notes.
+class Notes {
+  constructor(dir, scope) {
+    Object.assign(this, { dir, scope })
+  }
+
+  #file(name) {
+    return path.join(this.dir, `${slug(name)}.md`)
+  }
+
+  // All notes: { name, description, type, body, links, file }
+  list() {
+    let files = []
+    try {
+      files = fs.readdirSync(this.dir).filter((f) => f.endsWith('.md') && f !== 'MEMORY.md')
+    } catch {}
+    return files
+      .map((f) => {
+        const text = fs.readFileSync(path.join(this.dir, f), 'utf8')
+        const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text)
+        const meta = Object.fromEntries((m?.[1] ?? '').split('\n').map((l) => /^(\w+):\s*(.*)$/.exec(l.trim())).filter(Boolean).map(([, k, v]) => [k, v.trim()]))
+        const body = (m ? m[2] : text).trim()
+        return {
+          scope: this.scope,
+          name: f.slice(0, -3),
+          description: meta.description || body.split('\n')[0].slice(0, 120),
+          type: TYPES.includes(meta.type) ? meta.type : 'project',
+          tags: tagList(meta.tags).filter((x) => !TYPES.includes(x)),
+          body,
+          links: [...new Set([...body.matchAll(LINK)].map((x) => slug(x[1])))],
+          file: path.join(this.dir, f),
+        }
+      })
+      .sort((a, b) => a.name.localeCompare(b.name))
+  }
+
+  read(name) {
+    const note = this.list().find((n) => n.name === slug(name))
+    if (!note) return null
+    const backlinks = this.list().filter((n) => n.links.includes(note.name)).map((n) => `[[${n.name}]]`)
+    return { ...note, backlinks }
+  }
+
+  // Creates or replaces a note; returns its name.
+  write({ name, description, type, tags, content }) {
+    const n = slug(name || description)
+    const old = this.read(n)
+    const t = TYPES.includes(type) ? type : (old?.type ?? 'project')
+    const d = String(description || old?.description || String(content).split('\n')[0]).replace(/\s+/g, ' ').trim().slice(0, 200)
+    const g = (tagList(tags).length ? tagList(tags) : (old?.tags ?? [])).filter((x) => !TYPES.includes(x)) // the type is not a tag
+    fs.mkdirSync(this.dir, { recursive: true })
+    fs.writeFileSync(this.#file(n), `---\nname: ${n}\ndescription: ${d}\ntype: ${t}\ntags: ${g.join(', ')}\n---\n\n${String(content ?? old?.body ?? '').trim()}\n`)
+    this.changed()
+    return n
+  }
+
+  delete(name) {
+    try {
+      fs.rmSync(this.#file(name))
+    } catch {
+      return false
+    }
+    this.changed()
+    return true
+  }
+
+  // Notes with every word of the query in their name, description, tags or text; "tag:deploy" by tag.
+  search(query) {
+    const words = String(query).toLowerCase().split(/\s+/).filter(Boolean)
+    return this.list().filter((n) =>
+      words.every((w) => (w.startsWith('tag:') ? n.tags.includes(w.slice(4)) : `${n.name} ${n.description} ${n.tags.join(' ')} ${n.body}`.toLowerCase().includes(w))),
+    )
+  }
+
+  // "tag (count)" for every tag: all the system prompt carries about the memory.
+  tagSummary() {
+    const count = new Map()
+    for (const n of this.list()) for (const t of n.tags) count.set(t, (count.get(t) ?? 0) + 1)
+    return [...count].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([t, k]) => `${t} (${k})`).join(', ')
+  }
+
+  relevant(text, max = 6) {
+    return relevantOf(this.list(), text, max)
+  }
+
+  // [[links]] to notes that don't exist: found by code, fixed when tidying.
+  brokenLinks() {
+    const names = new Set(this.list().map((n) => n.name))
+    return this.list().flatMap((n) => n.links.filter((l) => !names.has(l)).map((l) => ({ from: n.name, to: l })))
+  }
+
+  // The index for the system prompt: one line per note, grouped by type. '' without notes.
+  index(max = 120) {
+    const notes = this.list()
+    const lines = []
+    for (const t of TYPES) {
+      const of = notes.filter((n) => n.type === t)
+      if (of.length) lines.push(`${t}:`, ...of.map((n) => `- [[${n.name}]] — ${n.description}${n.tags.length ? ` #${n.tags.join(' #')}` : ''}`))
+    }
+    return lines.length > max ? [...lines.slice(0, max), `… ${lines.length - max} more lines (search the memory)`].join('\n') : lines.join('\n')
+  }
+
+  // Keeps MEMORY.md in step with the notes.
+  changed() {
+    fs.mkdirSync(this.dir, { recursive: true })
+    const what = this.scope === 'global' ? 'The notes HeartCode keeps about you, for every project' : "This project's notes, kept by HeartCode"
+    fs.writeFileSync(path.join(this.dir, 'MEMORY.md'), `# Memory\n\n${what}. Each line links to a note.\n\n${this.index(Infinity) || '(no notes yet)'}\n`)
+  }
+}
+
+// Both memories as one: reading, searching and matching look in both (the project's note wins on
+// the same name); writing goes to the scope asked for, or where the note already is.
+export class Memory {
+  constructor(root, globalDir = path.join(HOME, 'memory')) {
+    this.project = new Notes(path.join(root, '.heartcode', 'memory'), 'project')
+    this.global = new Notes(globalDir, 'global')
+  }
+
+  #in(scope) {
+    return scope === 'global' ? this.global : this.project
+  }
+
+  list() {
+    return [...this.project.list(), ...this.global.list()]
+  }
+
+  read(name, scope) {
+    const n = slug(name)
+    const note = this.list().find((x) => x.name === n && (!scope || x.scope === scope))
+    if (!note) return null
+    return { ...note, backlinks: this.list().filter((x) => x.links.includes(n) && x !== note).map((x) => `[[${x.name}]]`) }
+  }
+
+  write(note) {
+    const where = note.scope === 'global' || note.scope === 'project' ? note.scope : (this.read(note.name)?.scope ?? 'project')
+    return this.#in(where).write(note)
+  }
+
+  delete(name, scope) {
+    const where = scope ?? this.read(name)?.scope
+    return where ? this.#in(where).delete(name) : false
+  }
+
+  search(query) {
+    return [...this.project.search(query), ...this.global.search(query)]
+  }
+
+  brokenLinks() {
+    const names = new Set(this.list().map((n) => n.name))
+    return this.list().flatMap((n) => n.links.filter((l) => !names.has(l)).map((l) => ({ from: n.name, to: l })))
+  }
+
+  tagSummary() {
+    const count = new Map()
+    for (const n of this.list()) for (const t of n.tags) count.set(t, (count.get(t) ?? 0) + 1)
+    return [...count].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([t, k]) => `${t} (${k})`).join(', ')
+  }
+
+  relevant(text, max = 6) {
+    return relevantOf(this.list(), text, max)
+  }
+
+  index(max) {
+    return [this.project.index(max), this.global.index(max) && `global:\n${this.global.index(max)}`].filter(Boolean).join('\n')
+  }
+}
+
+// The notes worth attaching to a message: the user's ways of working (user/feedback notes, a
+// few), plus notes whose tags, name or description share words with it. Most relevant first.
+function relevantOf(notes, text, max) {
+  const words = new Set(keywords(text))
+  const scored = notes.map((n) => {
+    let score = 0
+    for (const t of n.tags) if (keywords(t).some((w) => words.has(w))) score += 3
+    for (const w of keywords(n.name)) if (words.has(w)) score += 2
+    for (const w of keywords(n.description)) if (words.has(w)) score += 1
+    return { n, score }
+  })
+  const rules = scored.filter((x) => x.n.type === 'user' || x.n.type === 'feedback').sort((a, b) => b.score - a.score).slice(0, 4)
+  const matched = scored.filter((x) => x.score >= 2 && !rules.includes(x)).sort((a, b) => b.score - a.score)
+  return [...rules, ...matched].slice(0, max).map((x) => x.n)
+}
+
+const tagList = (v) => (Array.isArray(v) ? v : String(v ?? '').split(/[,\s#]+/)).map((t) => slug(t)).filter((t) => t && t !== 'note').slice(0, 5)
+
+// Words worth matching on: lowercased, without short or very common words, plural/-ing cut off.
+const STOP = new Set('the and for with this that from have what when where which into your you our are was were can will should could would about there their them then than just also only some more most very please make like want need does doing done how why who its it\'s use using'.split(' '))
+function keywords(text) {
+  return String(text)
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length > 2 && !STOP.has(w))
+    .map((w) => (w.length > 5 && w.endsWith('ing') ? w.slice(0, -3) : w.length > 4 && w.endsWith('ed') ? w.slice(0, -2) : w.length > 3 && /[^s]s$/.test(w) ? w.slice(0, -1) : w))
+}

package/src/oauth.js

@@ -0,0 +1,122 @@
+// OAuth sign-in for remote MCP servers, as the MCP authorization spec has it: the server answers
+// 401 → its metadata names the authorization server → HeartCode registers itself there (dynamic
+// client registration, or the clientId from the config) → the browser opens the sign-in page →
+// it comes back to a one-off local page with a code (PKCE) → tokens, kept in ~/.heart/mcp-auth.json
+// (only readable by you) and refreshed when they expire.
+import http from 'node:http'
+import path from 'node:path'
+import { createHash, randomBytes } from 'node:crypto'
+import { HOME, readJson, writeJson } from './config.js'
+import { log } from './log.js'
+
+const FILE = path.join(HOME, 'mcp-auth.json')
+const b64url = (buf) => Buffer.from(buf).toString('base64url')
+const store = () => readJson(FILE, {})
+const keep = (url, entry) => writeJson(FILE, { ...store(), [url]: entry })
+export const forget = (url) => {
+  const all = store()
+  delete all[url]
+  writeJson(FILE, all)
+}
+
+async function getJson(url, init = {}) {
+  const res = await fetch(url, { ...init, headers: { accept: 'application/json', ...init.headers }, signal: init.signal ?? AbortSignal.timeout(20_000) })
+  const text = await res.text()
+  if (!res.ok) throw Object.assign(new Error(`${res.status} from ${url}: ${text.slice(0, 200)}`), { status: res.status })
+  return JSON.parse(text)
+}
+
+// The authorization server's endpoints for an MCP server (wwwAuth: its 401's WWW-Authenticate).
+export async function discover(serverUrl, wwwAuth = '') {
+  const u = new URL(serverUrl)
+  const named = /resource_metadata="([^"]+)"/.exec(wwwAuth)?.[1]
+  const tail = u.pathname.replace(/\/$/, '')
+  let resource = {}
+  for (const url of named ? [named] : [`${u.origin}/.well-known/oauth-protected-resource${tail}`, `${u.origin}/.well-known/oauth-protected-resource`]) {
+    try {
+      resource = await getJson(url)
+      if (resource.authorization_servers?.length) break
+    } catch {}
+  }
+  const issuer = new URL(resource.authorization_servers?.[0] ?? u.origin)
+  const p = issuer.pathname.replace(/\/$/, '')
+  for (const url of [`${issuer.origin}/.well-known/oauth-authorization-server${p}`, `${issuer.origin}/.well-known/openid-configuration${p}`, ...(p ? [`${issuer.origin}${p}/.well-known/openid-configuration`] : [])]) {
+    try {
+      const meta = await getJson(url)
+      if (meta.authorization_endpoint && meta.token_endpoint) return { ...meta, scopes: resource.scopes_supported }
+    } catch {}
+  }
+  // servers from before the metadata documents: the default endpoints
+  return { authorization_endpoint: `${issuer.origin}/authorize`, token_endpoint: `${issuer.origin}/token`, registration_endpoint: `${issuer.origin}/register`, scopes: resource.scopes_supported }
+}
+
+async function tokenRequest(endpoint, params) {
+  const t = await getJson(endpoint, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams(Object.entries(params).filter(([, v]) => v)) })
+  if (!t.access_token) throw new Error(`no access token from ${endpoint}`)
+  return t
+}
+
+const entryFrom = (t, base) => ({ ...base, accessToken: t.access_token, refreshToken: t.refresh_token ?? base.refreshToken, expiresAt: t.expires_in ? Date.now() + t.expires_in * 1000 : null })
+
+// The saved token for this server, refreshed first when it has expired; null when there is none
+// (or it can't be refreshed): then it's time to sign in.
+export async function savedToken(url, { force = false } = {}) {
+  const e = store()[url]
+  if (!e?.accessToken) return null
+  if (!force && (!e.expiresAt || e.expiresAt > Date.now() + 60_000)) return e.accessToken
+  if (!e.refreshToken) return null
+  try {
+    const entry = entryFrom(await tokenRequest(e.tokenEndpoint, { grant_type: 'refresh_token', refresh_token: e.refreshToken, client_id: e.clientId, client_secret: e.clientSecret, resource: url }), e)
+    keep(url, entry)
+    log('oauth', `refreshed the token for ${url}`)
+    return entry.accessToken
+  } catch (e2) {
+    log('oauth', `refresh failed for ${url}: ${e2.message}`)
+    return null
+  }
+}
+
+// Signs in: open(url) shows the user the sign-in page (the browser); resolves to the access token.
+// opts: { clientId, clientSecret, callbackPort, scope } from the server's "oauth" config.
+export async function signIn(url, wwwAuth, open, { signal, oauth = {} } = {}) {
+  const meta = await discover(url, wwwAuth)
+  const server = http.createServer()
+  await new Promise((resolve, reject) => server.once('error', reject).listen(Number(oauth.callbackPort) || 0, '127.0.0.1', resolve))
+  try {
+    const redirect = `http://127.0.0.1:${server.address().port}/callback`
+    let client = { client_id: oauth.clientId, client_secret: oauth.clientSecret }
+    if (!client.client_id) {
+      if (!meta.registration_endpoint) throw new Error(`${url} has no client registration: give "oauth": { "clientId": … } in its config`)
+      client = await getJson(meta.registration_endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ client_name: 'HeartCode', redirect_uris: [redirect], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], token_endpoint_auth_method: 'none' }),
+      })
+    }
+    const verifier = b64url(randomBytes(32))
+    const state = b64url(randomBytes(16))
+    const auth = new URL(meta.authorization_endpoint)
+    const scope = oauth.scope ?? meta.scopes?.join(' ')
+    for (const [k, v] of Object.entries({ response_type: 'code', client_id: client.client_id, redirect_uri: redirect, code_challenge: b64url(createHash('sha256').update(verifier).digest()), code_challenge_method: 'S256', state, resource: url, scope })) if (v) auth.searchParams.set(k, v)
+    const code = await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('no sign-in within 5 minutes')), 300_000)
+      signal?.addEventListener('abort', () => (clearTimeout(timer), reject(Object.assign(new Error('stopped'), { name: 'AbortError' }))), { once: true })
+      server.on('request', (req, res) => {
+        const q = new URL(req.url, redirect)
+        if (q.pathname !== '/callback') return res.writeHead(404).end()
+        const ok = q.searchParams.get('state') === state && q.searchParams.get('code')
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(`<!doctype html><meta charset="utf-8"><title>HeartCode</title><body style="font:16px system-ui;padding:40px">${ok ? '♥ Signed in. You can close this tab and go back to HeartCode.' : `Sign-in failed: ${String(q.searchParams.get('error_description') ?? q.searchParams.get('error') ?? 'wrong state').replace(/</g, '&lt;')}`}</body>`)
+        clearTimeout(timer)
+        ok ? resolve(ok) : reject(new Error(`sign-in failed: ${q.searchParams.get('error_description') ?? q.searchParams.get('error') ?? 'the reply did not match'}`))
+      })
+      open(auth.href)
+    })
+    const base = { clientId: client.client_id, clientSecret: client.client_secret, tokenEndpoint: meta.token_endpoint }
+    const entry = entryFrom(await tokenRequest(meta.token_endpoint, { grant_type: 'authorization_code', code, redirect_uri: redirect, client_id: client.client_id, client_secret: client.client_secret, code_verifier: verifier, resource: url }), base)
+    keep(url, entry)
+    log('oauth', `signed in to ${url}`)
+    return entry.accessToken
+  } finally {
+    server.close()
+  }
+}

package/src/patch.js

@@ -0,0 +1,96 @@
+// apply_patch: the patch format OpenAI's models (GPT-4.1+, gpt-oss, Codex) are trained to write.
+// Several files in one go: added, deleted, changed, moved.
+//   *** Begin Patch
+//   *** Add File: hello.txt
+//   +Hello
+//   *** Update File: src/app.js
+//   *** Move to: src/main.js        (optional)
+//   @@ function main() {           (optional: a line just above, to find the right place)
+//    context line
+//   -removed line
+//   +added line
+//   *** Delete File: old.js
+//   *** End Patch
+// Each changed part is matched like edit_file's search text (applyEdit: exact, else ignoring
+// indentation), so a slightly off context still applies.
+import { applyEdit } from './edit.js'
+
+// → [{ type: 'add' | 'delete' | 'update', path, moveTo?, content?, chunks?: [{ header, old, new }] }]
+export function parsePatch(text) {
+  const lines = String(text ?? '').replace(/\r\n/g, '\n').split('\n')
+  let i = lines.findIndex((l) => l.trim() === '*** Begin Patch')
+  if (i === -1) throw new Error('the patch must start with "*** Begin Patch"')
+  const ops = []
+  let op = null
+  let chunk = null
+  const newChunk = (header = '') => op.chunks.push((chunk = { header, old: [], new: [] }))
+  for (i++; i < lines.length; i++) {
+    const l = lines[i]
+    let m
+    if (l.trim() === '*** End Patch') return ops
+    if ((m = /^\*\*\* (Add|Delete|Update) File: (.+)$/.exec(l))) {
+      op = { type: m[1].toLowerCase(), path: m[2].trim(), ...(m[1] === 'Add' && { content: [] }), ...(m[1] === 'Update' && { chunks: [] }) }
+      chunk = null
+      ops.push(op)
+      continue
+    }
+    if (!op) {
+      if (l.trim()) throw new Error(`line ${i + 1}: expected "*** Add File:", "*** Update File:" or "*** Delete File:", got "${l}"`)
+      continue
+    }
+    if (op.type === 'add') {
+      if (l.startsWith('+')) op.content.push(l.slice(1))
+      else if (l.trim()) throw new Error(`line ${i + 1}: in an added file every line starts with "+"`)
+      continue
+    }
+    if (op.type === 'delete') continue
+    if ((m = /^\*\*\* Move to: (.+)$/.exec(l))) {
+      op.moveTo = m[1].trim()
+      continue
+    }
+    if (l.startsWith('@@')) {
+      newChunk(l.replace(/^@@\s?/, '').replace(/\s*@@$/, '').trim())
+      continue
+    }
+    if (l.trim() === '*** End of File') continue
+    if (!chunk) newChunk()
+    const mark = l[0]
+    if (mark === '+') chunk.new.push(l.slice(1))
+    else if (mark === '-') chunk.old.push(l.slice(1))
+    else {
+      const ctx = mark === ' ' ? l.slice(1) : l // models drop the space on blank context lines
+      chunk.old.push(ctx)
+      chunk.new.push(ctx)
+    }
+  }
+  throw new Error('the patch must end with "*** End Patch"')
+}
+
+// One file's chunks applied to its text → { text } or { error }.
+export function applyChunks(text, chunks) {
+  let out = text
+  for (const [n, ch] of chunks.entries()) {
+    const label = chunks.length > 1 ? `part ${n + 1}: ` : ''
+    const old = ch.old.join('\n')
+    const next = ch.new.join('\n')
+    if (!old.trim()) {
+      // only added lines: after the @@ line, else at the end
+      const at = ch.header ? out.indexOf(ch.header) : -1
+      if (ch.header && at === -1) return { error: `${label}the @@ line "${ch.header}" was not found` }
+      const end = at === -1 ? out.length : out.indexOf('\n', at) === -1 ? out.length : out.indexOf('\n', at) + 1
+      const before = out.slice(0, end)
+      out = before + (before && !before.endsWith('\n') ? '\n' : '') + next + '\n' + out.slice(end)
+      continue
+    }
+    let r = applyEdit(out, old, next)
+    if (r.error && ch.header && out.includes(ch.header)) {
+      // several places match: the one after the @@ line
+      const at = out.indexOf(ch.header)
+      const tail = applyEdit(out.slice(at), old, next)
+      if (!tail.error) r = { text: out.slice(0, at) + tail.text }
+    }
+    if (r.error) return { error: label + r.error.replace('SEARCH text', 'context and - lines') }
+    out = r.text
+  }
+  return { text: out }
+}