loopat 0.1.0

package/server/src/files.ts

@@ -0,0 +1,173 @@
+import { readdir, readFile, writeFile, stat, mkdir, rm, unlink } from "node:fs/promises"
+import { join, normalize, relative, sep, dirname } from "node:path"
+import { loopDir } from "./paths"
+
+export type FileEntry = {
+  name: string
+  path: string // relative to workdir, posix-style
+  type: "file" | "dir"
+  size?: number
+}
+
+function safeJoin(rootAbs: string, rel: string): string | null {
+  const candidate = normalize(join(rootAbs, rel))
+  const insideRel = relative(rootAbs, candidate)
+  if (insideRel.startsWith("..") || insideRel.startsWith("/" + sep)) return null
+  return candidate
+}
+
+const SKIP_DIRS = new Set(["node_modules", ".git", ".bun", ".claude"])
+
+export async function listDir(loopId: string, relPath: string): Promise<FileEntry[]> {
+  const root = loopDir(loopId)
+  const abs = safeJoin(root, relPath)
+  if (!abs) throw new Error("path escapes workdir")
+  let names: string[] = []
+  try {
+    names = await readdir(abs)
+  } catch {
+    return []
+  }
+  const out: FileEntry[] = []
+  for (const name of names) {
+    if (SKIP_DIRS.has(name)) continue
+    if (name === ".git" || name === ".DS_Store") continue
+    const childRel = relPath ? `${relPath}/${name}` : name
+    let isDir = false
+    let size: number | undefined
+    try {
+      // stat follows symlinks → symlinked-dir reports as dir
+      const s = await stat(join(abs, name))
+      isDir = s.isDirectory()
+      if (!isDir) size = s.size
+    } catch {
+      continue
+    }
+    out.push({ name, path: childRel, type: isDir ? "dir" : "file", size })
+  }
+  out.sort((a, b) => {
+    if (a.type !== b.type) return a.type === "dir" ? -1 : 1
+    return a.name.localeCompare(b.name)
+  })
+  return out
+}
+
+const MAX_BYTES = 256 * 1024
+
+export async function readWorkdirFile(loopId: string, relPath: string): Promise<{ content: string; truncated: boolean; size: number } | null> {
+  const root = loopDir(loopId)
+  const abs = safeJoin(root, relPath)
+  if (!abs) return null
+  try {
+    const s = await stat(abs)
+    if (!s.isFile()) return null
+    const truncated = s.size > MAX_BYTES
+    const buf = await readFile(abs)
+    const slice = truncated ? buf.subarray(0, MAX_BYTES) : buf
+    return { content: slice.toString("utf8"), truncated, size: s.size }
+  } catch {
+    return null
+  }
+}
+
+export async function writeWorkdirFile(loopId: string, relPath: string, content: string): Promise<boolean> {
+  const root = loopDir(loopId)
+  const abs = safeJoin(root, relPath)
+  if (!abs) return false
+  try {
+    await mkdir(dirname(abs), { recursive: true })
+    await writeFile(abs, content)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function deleteWorkdirFile(loopId: string, relPath: string): Promise<boolean> {
+  const root = loopDir(loopId)
+  const abs = safeJoin(root, relPath)
+  if (!abs) return false
+  try {
+    const s = await stat(abs)
+    if (s.isDirectory()) {
+      await rm(abs, { recursive: true, force: true })
+    } else {
+      await unlink(abs)
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function createWorkdirFolder(loopId: string, relPath: string): Promise<boolean> {
+  const root = loopDir(loopId)
+  const abs = safeJoin(root, relPath)
+  if (!abs) return false
+  try {
+    await mkdir(abs, { recursive: true })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const MAX_RECURSIVE_ENTRIES = 5000
+const MAX_RECURSIVE_DEPTH = 20
+
+/**
+ * Recursively list all files and directories under a root path within a loop.
+ * Returns a flat array sorted dirs-first then alpha. One HTTP call replaces
+ * the frontend's recursive fetchAllFiles waterfall.
+ */
+export async function listDirRecursive(
+  loopId: string,
+  relPath: string,
+): Promise<FileEntry[]> {
+  const root = loopDir(loopId)
+  const abs = safeJoin(root, relPath)
+  if (!abs) return []
+
+  const result: FileEntry[] = []
+  const skip = new Set(SKIP_DIRS)
+  skip.add(".git").add(".DS_Store")
+
+  async function walk(absPath: string, prefix: string, depth: number) {
+    if (result.length >= MAX_RECURSIVE_ENTRIES) return
+    if (depth > MAX_RECURSIVE_DEPTH) return
+
+    let names: string[]
+    try {
+      names = await readdir(absPath)
+    } catch {
+      return
+    }
+
+    const entries: Array<{ name: string; isDir: boolean }> = []
+    for (const name of names) {
+      if (skip.has(name)) continue
+      try {
+        const s = await stat(join(absPath, name))
+        entries.push({ name, isDir: s.isDirectory() })
+      } catch {
+        continue
+      }
+    }
+    entries.sort((a, b) => {
+      if (a.isDir !== b.isDir) return a.isDir ? -1 : 1
+      return a.name.localeCompare(b.name)
+    })
+
+    for (const { name, isDir } of entries) {
+      if (result.length >= MAX_RECURSIVE_ENTRIES) break
+      const childRel = prefix ? `${prefix}/${name}` : name
+      result.push({ name, path: childRel, type: isDir ? "dir" : "file" })
+      if (isDir) {
+        await walk(join(absPath, name), childRel, depth + 1)
+      }
+    }
+  }
+
+  await walk(abs, relPath, 0)
+  return result
+}

package/server/src/git-crypt-key.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-user git-crypt symmetric key. Decrypts the user's personal repo
+ * worktree (specifically `.loopat/vaults/**`).
+ *
+ * Storage: host-secrets/<user>/git-crypt.key — host-only, NOT bound into the
+ * sandbox, NOT in any git repo. Mode 0600.
+ *
+ * Phase A (now): plain file on disk. Anyone with host access can read it and
+ * decrypt the repo. Trade-off documented — see design discussion notes.
+ *
+ * Phase B (future, optional upgrade): replace this module's read path with an
+ * in-memory map populated at server start via passphrase prompt. Callers stay
+ * the same — `getGitCryptKey(userId)` interface is the migration boundary.
+ */
+import { existsSync } from "node:fs"
+import { mkdir, readFile, writeFile, chmod } from "node:fs/promises"
+import { dirname } from "node:path"
+import { hostSecretsDir, personalGitCryptKeyPath } from "./paths"
+
+export async function getGitCryptKey(userId: string): Promise<Buffer> {
+  return await readFile(personalGitCryptKeyPath(userId))
+}
+
+export async function gitCryptKeyExists(userId: string): Promise<boolean> {
+  return existsSync(personalGitCryptKeyPath(userId))
+}
+
+export async function saveGitCryptKey(userId: string, keyData: Buffer): Promise<void> {
+  const dir = hostSecretsDir(userId)
+  await mkdir(dir, { recursive: true })
+  await chmod(dir, 0o700).catch(() => {})
+  const path = personalGitCryptKeyPath(userId)
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, keyData, { mode: 0o600 })
+  await chmod(path, 0o600).catch(() => {})
+}

package/server/src/git-host.ts

@@ -0,0 +1,104 @@
+/**
+ * Git host provider abstraction — docs/identity.md's five-capability contract
+ * as a pluggable interface. A GitHostProvider adapts ONE git platform (GitHub,
+ * GitLab, an internal host, …) onto the five operations loopat needs to onboard
+ * a user. loopat core stays platform-agnostic.
+ *
+ * To add a platform: implement this interface and `registerProvider()` it —
+ * see server/src/providers.ts (the explicit registry). Nothing in core changes.
+ */
+
+export type HostCred = { token: string; baseUrl?: string }
+export type RepoRef = { owner: string; name: string }
+
+export interface GitHostProvider {
+  readonly id: string
+  readonly label: string
+
+  /** Optional: where/how the user gets a token, shown in the onboarding token
+   *  step. A URL or short hint. Platform-specific, so the provider supplies it
+   *  (core stays platform-agnostic). */
+  readonly tokenHelp?: string
+
+  /**
+   * How git authenticates clone/push on this platform:
+   *  - "ssh-deploy-key": loopat generates an ssh key, the provider registers it
+   *    (registerDeployKey), and git uses ssh. (GitHub.)
+   *  - "https-token": git uses `https://oauth2:<token>@…`; no key is registered.
+   *    (GitLab / internal — one token does API + git.)
+   */
+  readonly gitAuthMode: "ssh-deploy-key" | "https-token"
+
+  /** ① authenticate — turn a credential into the user's login (+ email for
+   *  commit authorship, where the platform enforces a valid address). */
+  authenticate(cred: HostCred): Promise<{ login: string; email?: string }>
+
+  /** ② create a private repo in the user's namespace if missing. */
+  ensureRepo(
+    cred: HostCred,
+    name: string,
+    opts?: { private?: boolean },
+  ): Promise<{ url: string; created: boolean }>
+
+  /** ③ register a deploy key on a repo (only for "ssh-deploy-key" mode). */
+  registerDeployKey?(
+    cred: HostCred,
+    repo: RepoRef,
+    title: string,
+    pubkey: string,
+    readOnly: boolean,
+  ): Promise<void>
+
+  /** ④ register an account-level key (only for "ssh-deploy-key" mode). */
+  registerUserKey?(cred: HostCred, title: string, pubkey: string): Promise<void>
+
+  /** ⑤ grant a member access to a repo (usually admin-gated). */
+  grantAccess(
+    cred: HostCred,
+    repo: RepoRef,
+    login: string,
+    level: "read" | "write",
+  ): Promise<void>
+
+  /** List the user's repos (names) for an onboarding picker. Optional. */
+  listRepos?(cred: HostCred): Promise<{ name: string; path: string }[]>
+
+  /**
+   * Optional internal-setup hook. Runs once during personal-repo init, right
+   * after `git-crypt init` (so `.gitattributes` already encrypts
+   * `.loopat/vaults/**`) and before the scaffold is committed + pushed. Use it
+   * to seed default files into the working tree — provider configs, ssh keys,
+   * jumpbox configs, … This is where a team bakes its internal defaults.
+   *
+   * Encryption boundary: files under `.loopat/vaults/**` are git-crypt
+   * encrypted; everything else (e.g. `.loopat/config.json`) is committed in
+   * PLAINTEXT — so never write real secrets outside the vault (use env-var
+   * refs like `"$FOO_API_KEY"` in config.json instead).
+   *
+   * loopat stages (`git add .loopat memory`), commits and pushes whatever you
+   * write. Throwing only logs a warning — setup still succeeds.
+   *
+   *   ctx.repoDir  — cloned working tree (write paths relative to this)
+   *   ctx.vaultDir — `${repoDir}/.loopat/vaults/default` (encrypted)
+   *   ctx.userId   — the loopat user being set up
+   *   ctx.login    — their login on this platform
+   */
+  seedDefaults?(ctx: {
+    repoDir: string
+    vaultDir: string
+    userId: string
+    login: string
+  }): Promise<void>
+}
+
+const providers = new Map<string, GitHostProvider>()
+
+export function registerProvider(p: GitHostProvider): void {
+  providers.set(p.id, p)
+}
+export function getProvider(id: string): GitHostProvider | undefined {
+  return providers.get(id)
+}
+export function listProviders(): { id: string; label: string }[] {
+  return [...providers.values()].map((p) => ({ id: p.id, label: p.label }))
+}

package/server/src/github.ts

@@ -0,0 +1,161 @@
+/**
+ * GitHub integration — the five-capability contract from docs/identity.md,
+ * implemented against the GitHub REST API. It only ever consumes a *token*;
+ * how that token was obtained (a user-pasted PAT today, an OAuth grant later)
+ * is not its concern. Swapping the token source never touches this client.
+ *
+ * `baseUrl` is configurable so the same client works against github.com
+ * (https://api.github.com) or a GitHub Enterprise / internal host
+ * (https://<host>/api/v3).
+ */
+import { registerProvider, type GitHostProvider } from "./git-host"
+
+export type GithubClient = {
+  baseUrl: string
+  token: string
+}
+
+export function githubClient(token: string, baseUrl = "https://api.github.com"): GithubClient {
+  return { token, baseUrl: baseUrl.replace(/\/+$/, "") }
+}
+
+async function gh<T = any>(
+  c: GithubClient,
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<{ status: number; data: T }> {
+  const res = await fetch(`${c.baseUrl}${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${c.token}`,
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      ...(body ? { "Content-Type": "application/json" } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  let data: any = null
+  const text = await res.text()
+  if (text) {
+    try { data = JSON.parse(text) } catch { data = text }
+  }
+  return { status: res.status, data }
+}
+
+function fail(op: string, r: { status: number; data: any }): never {
+  const msg = r.data?.message ?? (typeof r.data === "string" ? r.data : "")
+  throw new Error(`github ${op} failed (${r.status})${msg ? `: ${msg}` : ""}`)
+}
+
+/** Capability 1 — authenticate: turn a token into the user's login. */
+export async function getViewer(c: GithubClient): Promise<{ login: string; id: number }> {
+  const r = await gh(c, "GET", "/user")
+  if (r.status !== 200) fail("authenticate", r)
+  return { login: r.data.login, id: r.data.id }
+}
+
+/**
+ * Capability 2 — create a private repo in the viewer's namespace if missing.
+ * Returns the clone URLs; idempotent (existing repo → returned as-is).
+ */
+export async function ensureUserRepo(
+  c: GithubClient,
+  name: string,
+  opts: { private?: boolean; description?: string } = {},
+): Promise<{ created: boolean; sshUrl: string; httpUrl: string; fullName: string }> {
+  const me = await getViewer(c)
+  const existing = await gh(c, "GET", `/repos/${me.login}/${name}`)
+  if (existing.status === 200) {
+    return {
+      created: false,
+      sshUrl: existing.data.ssh_url,
+      httpUrl: existing.data.clone_url,
+      fullName: existing.data.full_name,
+    }
+  }
+  if (existing.status !== 404) fail("get repo", existing)
+  const r = await gh(c, "POST", "/user/repos", {
+    name,
+    private: opts.private ?? true,
+    description: opts.description ?? "loopat",
+    auto_init: false,
+  })
+  if (r.status !== 201) fail("create repo", r)
+  return { created: true, sshUrl: r.data.ssh_url, httpUrl: r.data.clone_url, fullName: r.data.full_name }
+}
+
+/** Capability 3 — register a deploy key on a repo (bootstrap clone of personal). */
+export async function ensureDeployKey(
+  c: GithubClient,
+  owner: string,
+  repo: string,
+  title: string,
+  publicKey: string,
+  readOnly = true,
+): Promise<void> {
+  const list = await gh(c, "GET", `/repos/${owner}/${repo}/keys`)
+  if (list.status === 200 && Array.isArray(list.data) && list.data.some((k: any) => k.key?.trim() === publicKey.trim())) {
+    return
+  }
+  const r = await gh(c, "POST", `/repos/${owner}/${repo}/keys`, { title, key: publicKey, read_only: readOnly })
+  if (r.status !== 201 && r.status !== 422 /* already exists */) fail("add deploy key", r)
+}
+
+/** Capability 4 — register an account-level key (the runtime key in the vault). */
+export async function ensureUserKey(c: GithubClient, title: string, publicKey: string): Promise<void> {
+  const list = await gh(c, "GET", "/user/keys")
+  if (list.status === 200 && Array.isArray(list.data) && list.data.some((k: any) => k.key?.trim() === publicKey.trim())) {
+    return
+  }
+  const r = await gh(c, "POST", "/user/keys", { title, key: publicKey })
+  if (r.status !== 201 && r.status !== 422) fail("add user key", r)
+}
+
+/**
+ * Capability 5 — grant a member access to a repo. Admin-gated by GitHub:
+ * `c` must be a token with admin on `owner/repo` (e.g. an org-admin token at
+ * team-setup time), not the joining user's own token.
+ */
+export async function ensureCollaborator(
+  c: GithubClient,
+  owner: string,
+  repo: string,
+  username: string,
+  permission: "pull" | "push" | "admin" = "push",
+): Promise<void> {
+  const r = await gh(c, "PUT", `/repos/${owner}/${repo}/collaborators/${username}`, { permission })
+  // 201 = invitation created, 204 = already a collaborator
+  if (r.status !== 201 && r.status !== 204) fail("add collaborator", r)
+}
+
+/** The built-in GitHub provider — adapts the functions above onto GitHostProvider. */
+export const githubProvider: GitHostProvider = {
+  id: "github",
+  label: "GitHub",
+  gitAuthMode: "ssh-deploy-key",
+  async authenticate(cred) {
+    return await getViewer(githubClient(cred.token, cred.baseUrl))
+  },
+  async ensureRepo(cred, name, opts) {
+    const r = await ensureUserRepo(githubClient(cred.token, cred.baseUrl), name, { private: opts?.private })
+    return { url: r.sshUrl, created: r.created }
+  },
+  async registerDeployKey(cred, repo, title, pubkey, readOnly) {
+    await ensureDeployKey(githubClient(cred.token, cred.baseUrl), repo.owner, repo.name, title, pubkey, readOnly)
+  },
+  async registerUserKey(cred, title, pubkey) {
+    await ensureUserKey(githubClient(cred.token, cred.baseUrl), title, pubkey)
+  },
+  async grantAccess(cred, repo, login, level) {
+    await ensureCollaborator(
+      githubClient(cred.token, cred.baseUrl),
+      repo.owner,
+      repo.name,
+      login,
+      level === "write" ? "push" : "pull",
+    )
+  },
+}
+
+registerProvider(githubProvider)