wiki-viewer 1.14.1 → 1.14.2

package/.next/standalone/.handoffs/archive/handoff-20260612-113332.md

@@ -1,98 +0,0 @@
-# Handoff: Git-backed read-only workspaces (feature complete + perf optimization shipped)
-
-- **Written:** 2026-06-12 11:33:32 UTC
-- **From session:** unknown (pi agent, not Claude Code CLI; no .jsonl pointer)
-- **Working dir:** /home/sil/wiki-viewer
-- **Resume raw transcript (fallback only):** n/a (pi session, no --resume id captured)
-
-## Goal
-
-Let teams browse docs that live in a remote git repo (GitHub/GitLab/Bitbucket/Gitea/GHE)
-with the full wiki-viewer UI, instead of reading raw files on the host. Scope was locked
-early: **read-only**, **private repos via HTTPS PAT**, **manual refresh** (no webhook/cron).
-"Done" = admin pastes a repo URL, server clones it, it shows up as a normal workspace that
-is read-only, with a Refresh button. Plus a perf path for repos whose docs sit in a subdir.
-
-This work is **shipped and complete**. Both commits pushed to origin/main. There is no
-pending task. This handoff exists to orient a fresh agent if the feature is extended.
-
-## Current state
-
-DONE and pushed. Two commits on `main`:
-
-- `750f1e6` feat: git-backed read-only workspaces (backend spine + UI + tests)
-- `52edf40` perf(git): optional subpath via sparse checkout
-
-Working tree clean. `pnpm test` = 371 pass / 0 fail. `pnpm exec tsc --noEmit` clean.
-`pnpm build` succeeds (only the unrelated Better Auth base-URL warning, expected without env).
-
-What works end-to-end:
-
-- Add a git workspace via the directory picker "From Git" tab (URL, branch, subdir, username, token, name).
-- Server clones to `~/.wiki-viewer/repos/<wsId>/`, registers a `readOnly: true` workspace.
-- Optional subdir does a blobless partial clone + cone sparse-checkout; rootDir points at the subdir.
-- Every fs-mutating route rejects writes on a read-only workspace with 403 WORKSPACE_READ_ONLY.
-- Manual Refresh button in the switcher runs `git pull --ff-only`, shows synced time + last error.
-- PAT stored 0600 in `~/.wiki-viewer/git-secrets.json`, never in config.json, never logged, never in any API response.
-
-Nothing is half-built or untested in this feature.
-
-## Next action (do this first)
-
-Nothing pending. If asked to extend, the most likely next features (all explicitly deferred,
-not bugs) are listed under "Open questions". Start by reading the two key lib files below to
-rebuild the mental model, then `pnpm test` to confirm green baseline before any change.
-
-## Then
-
-Only if extending. Each item is a fresh mini-feature, use `/feature`:
-
-1. Config UI for `git.allowedHosts` / `git.allowInsecureHttp` (currently config.json only, no UI). Verify: admin can restrict clone hosts from settings.
-2. Write-back (commit + push or PR flow). This is the big scope cliff deliberately not built. Would require lifting read-only on a write path + conflict/precondition handling. Verify: edit in a git workspace reaches upstream.
-3. Auto-refresh (webhook or cron). Deferred by design; manual-only shipped. Verify: clone updates without a manual click.
-
-## Key files
-
-- `src/lib/git.ts` — git binary wrapper. `cloneRepo` (askpass auth so token never in argv/.git/config), `validateRemoteUrl` (https-only scheme gate + host allowlist + metachar reject), `validateSubpath`, `pullRepo` (ff-only), `headSha`, `currentBranch`, `assertGitAvailable`. Clone args: whole-repo `["clone","--depth","1","--single-branch","--no-tags",url,dest]`; subpath adds `--filter=blob:none --sparse` then `sparse-checkout set --cone <subpath>`.
-- `src/lib/git-secrets.ts` — PAT store, 0600 file, genTokenRef/setToken/getToken/deleteToken. Frozen, do not modify.
-- `src/lib/workspaces.ts` — `Workspace.readOnly` + `git{remoteUrl,branch,tokenRef,username,subpath,cloneRoot,lastPulledAt,lastSha,lastError}`. `createGitWorkspace`, `refreshGitWorkspace`, `removeWorkspace` (deletes cloneRoot, path.relative guard), `sanitizeWorkspace` (strips tokenRef from all responses).
-- `src/lib/workspace-context.ts` — `resolveWorkspaceForUser/Agent(req, intent)`. `intent:"write"` + `ws.readOnly` → 403 WORKSPACE_READ_ONLY. This is the single read-only chokepoint; every write route passes "write".
-- `src/lib/config.ts` — `reposDir()`, `WorkspaceGitEntry` (mirror of WorkspaceGit), `git.allowedHosts`/`git.allowInsecureHttp` config keys.
-- `src/app/api/system/workspaces/route.ts` — POST branches to createGitWorkspace when body.remoteUrl present; masks tokenRef.
-- `src/app/api/system/workspaces/[id]/refresh/route.ts` — admin+CSRF, calls refreshGitWorkspace.
-- `src/components/dir-picker.tsx` — "Local folder" / "From Git" mode toggle + the From Git form.
-- `src/app/page.tsx` — workspace switcher: read-only badge, Refresh button (handleRefreshWorkspace ~line 862, switcher render ~line 2015), timeAgo helper (~line 107).
-- `src/tests/proof/git.test.ts`, `git-secrets.test.ts`, `git-workspace.test.ts`, `readonly-enforcement.test.ts`, `git-sparse.test.ts` — full coverage.
-
-## Decisions & rationale
-
-- **Full clone, not API/lazy fetch.** Keeps reads as native fs (fast) and viewer/search/agent paths unchanged + provider-agnostic. API-based reads would be per-host and slow. See the read-perf discussion in session.
-- **Read-only is a policy, not a tech limit.** The clone is a writable dir, but edits there would be silently lost on `git pull --ff-only` (divergence) and never reach upstream. Read-only protects the user from edits with nowhere to go. Lift it only when write-back exists.
-- **Subpath uses sparse cone + blobless,** the only change that improves setup time without sacrificing read perf. `rootDir = cloneRoot/subpath` so `.git` sits outside rootDir (cleaner isolation). `cloneRoot` stored separately so refresh/remove target the real clone, not the subdir.
-- **Generalized beyond GitHub** because read-only clone+pull is provider-agnostic; only auth differs and HTTPS-token auth is uniform. Cheap to support all hosts.
-- **`--no-tags` on whole-repo, blobless only on subpath.** Depth-1 already fetches only tip blobs, so blobless adds negotiation cost for no gain on a full clone.
-
-## Gotchas & landmines
-
-- **`.git/` is already excluded** in indexer (SKIP_DIRS), fs/ls (SKIP_NAMES), and raw-fs (isDeniedRelPath). Do NOT re-add exclusions; subpath clones keep .git outside rootDir anyway.
-- **Local-protocol clones (`file://` or local path) IGNORE `--filter`** (git prints "filtering not recognized by server, ignoring"). Tests use local fixtures so they assert END STATE (only subpath files in rootDir), not transfer savings. Real https hosts get the blobless benefit.
-- **`agent-workspace-scope.test.ts` has a pre-existing flaky teardown race** (async agents.json write lands after the test's `rm`, ENOENT unhandledRejection). NOT caused by this feature; surfaced once under parallel load, then passed consistently. If the full suite flakes on exactly that file, it is this known race, not the git code.
-- **Symlink subpath attack is blocked twice:** git's `sparse-checkout set --cone` refuses a non-directory, AND createGitWorkspace does lstat + realpath-under-cloneRoot. Test `git-sparse.test.ts` covers it. The error message can be either "not a directory" (git) or "not found" (our guard) so the test regex accepts both.
-- **removeWorkspace delete guard** uses `path.relative(managed, cloneDir)` not raw `startsWith`, to stop a tampered config cloneRoot from deleting outside reposDir. Keep that if you touch cleanup.
-- **pnpm only.** `kysely` pinned 0.28.5 via overrides, do not bump. No em-dashes in any copy/comments (user rule). No AI attribution in commits.
-- Tests run from repo root: `pnpm exec tsx --import ./src/tests/proof/preload.ts --test src/tests/proof/<name>.test.ts`. preload.ts overrides HOME to a temp dir so tests never touch real ~/.wiki-viewer.
-
-## Open questions / waiting on
-
-None blocking. Deferred-by-design (not bugs): write-back/push, auto-refresh (webhook/cron),
-GHE-host config UI. All would be net-new features needing `/feature`, not continuations.
-
-## Mental model
-
-A git-backed workspace IS a normal workspace whose `rootDir` happens to be a server-managed
-clone. That single insight is why the feature is small: the entire read path (browser, editor
-view, search, agent reads) is untouched, because it just sees files on disk. Only two things
-are new: the clone/pull/secret orchestration (lib/git\*.ts + createGitWorkspace), and a
-read-only write gate centralized in one place (workspace-context resolver `intent` param).
-Everything else is wiring. When extending, ask "is this a read concern (already works) or a
-write concern (must go through the read-only gate)?" before touching anything.

package/.next/standalone/.handoffs/archive/handoff-20260612-141032.md

@@ -1,73 +0,0 @@
-# Handoff: Sub-folder git repo detection + branch badge + pull refresh
-
-- **Written:** 2026-06-12 14:10:32 UTC
-- **From session:** unknown (Pi agent, not Claude Code CLI)
-- **Working dir:** /home/sil/wiki-viewer
-- **Resume raw transcript (fallback only):** n/a (Pi session, no --resume id captured)
-
-## Goal
-
-Let users see git status for sub-folder git repos inside a normal workspace. When expanding a directory in the file tree sidebar, auto-detect any subdirectory that is a git repo root, show branch name + dirty indicator as an inline badge next to the folder name, and provide a pull-to-refresh button.
-
-"Done" = expand a folder in the sidebar, see `main` or `master` next to repo folders, click the refresh icon and see it pull latest + reload tree.
-
-## Current state
-
-Shipped and committed at `310cb72`. Working tree clean. `pnpm test` = 371 pass / 0 fail. `pnpm exec tsc --noEmit` clean.
-
-What works end-to-end:
-
-- `GET /api/wiki?dir=...` returns `git: {branch, dirty}` for each subdirectory that is a git repo root.
-- File tree sidebar shows `GitBranch icon branch [* if dirty] [↩ button]` inline.
-- Clicking ↩ calls `POST /api/wiki/git-pull` with `{path}`, runs `git pull --ff-only`, shows toast on success/fail, refreshes parent listing.
-- Reuses `detectGitRepo` in both listing and pull endpoint for consistent validation.
-- Pull endpoint uses `resolveWorkspaceForUser(request, "write")` — blocked on read-only workspaces.
-- Node-app entries also get git detection (review fix).
-- Follows existing patterns: CSRF, safeWorkspacePath, wsFetch, showError/showSuccess.
-
-## Next action (do this first)
-
-Nothing pending. If asked to extend, read the four changed files below to rebuild mental model, then `pnpm test` to confirm green baseline.
-
-## Then
-
-Possible extensions (all net-new, not continuations):
-
-1. **`.gitignore`-aware file listing** — hide ignored files from the tree. Requires running `git ls-files` in the sub-repo and filtering against `fetchDir` results.
-2. **Modification badges in tree** — `M`/`?`/`D` next to files when inside a detected git repo. Requires `git status --porcelain` on the sub-repo.
-3. **Git log / history panel** — show recent commits when clicking the branch badge.
-4. **Write-back (commit + push)** — big scope cliff. Would lift read-only and add commit UI.
-
-## Key files
-
-- `src/lib/git.ts` — added `detectGitRepo(dirPath)` at end of file. Returns `{branch, dirty}` or `null`. Uses `stat(.git)` then `rev-parse --show-toplevel` to confirm repo root, then `currentBranch()` + `status --porcelain`. Also added `GitRepoInfo` interface.
-- `src/app/api/wiki/route.ts` — GET handler extended to call `detectGitRepo` for each directory entry. Also restructured to apply git detection uniformly for all directory types (dir, app, node-app).
-- `src/app/api/wiki/git-pull/route.ts` — NEW file, POST endpoint. CSRF-protected, uses `resolveWorkspaceForUser(request, "write")`, validates path via `safeWorkspacePath`, reuses `detectGitRepo` for repo validation, runs `pullRepo` then returns `{branch, sha}`.
-- `src/app/page.tsx` — `TreeNode.git?` field; `fetchDir` passes through git from API; `pullingRepo` state + `handleGitPull` callback (after reloadDir definition); git badge + refresh button in `renderNodes` between node name and agent presence dot.
-
-## Decisions & rationale
-
-- **Auto-detect, not opt-in.** Scanning for `.git` on directory expand is cheap (one stat per subdirectory). Extra git commands only run for directories WITH `.git`. Zero config burden.
-- **Inline badge in tree row**, not status bar or tooltip. Always visible, no extra clicks. Same pattern as VSCode explorer.
-- **Reuse `detectGitRepo` in pull endpoint.** Ensures same validation (toplevel check, not just `.git` existence) prevents pulling on non-root repos or submodules.
-- **Pull on read-only workspaces blocked.** `resolveWorkspaceForUser(request, "write")` in git-pull endpoint prevents mutating a read-only git-backed workspace by pulling inside it.
-- **Node-app entries included.** Review flagged the early-return gap; restructured to detect git before type-specific branching. Node-app folders that are also git repos get the badge.
-- **Parent directory reloaded after pull.** Simpler and more accurate than trying to predict new dirty state.
-- **No rate limiting.** Frontend guard prevents concurrent pulls per path. Server-side throttle deferred until abuse surfaces.
-
-## Gotchas & landmines
-
-- **`reloadDir` defined before `handleGitPull`** in page.tsx. The callback depends on `reloadDir` being declared first. If you move callbacks around, keep this ordering.
-- **Submodules**: `.git` is a file (not dir) in submodule checkouts. `detectGitRepo` handles this because `stat()` works on both files and dirs. The `rev-parse --show-toplevel` check also handles this correctly.
-- **Symlink `.git`**: `stat` follows symlinks by default, so detection works. But `rev-parse --show-toplevel` resolves realpath, so comparison against symlinked dirPath would fail. This is acceptable — symlinked `.git` pointing outside the workspace is an unusual case.
-- **Nested git repos**: If a git repo has submodules, the submodule dirs are git repos too but `rev-parse --show-toplevel` returns the submodule root, not the superproject root. They each get their own badge, which is correct.
-- **pnpm only.** `kysely` pinned 0.28.5 via overrides, do not bump. No em-dashes in copy/comments (user rule). No AI attribution in commits.
-- **Tests run from repo root.** `pnpm exec tsx --import ./src/tests/proof/preload.ts --test src/tests/proof/<name>.test.ts`. preload.ts overrides HOME to temp dir.
-
-## Open questions / waiting on
-
-None. Feature is complete and committed.
-
-## Mental model
-
-A sub-folder git repo inside a workspace is just a normal directory with a `.git` file/dir. The whole feature is three layers: (1) detection — one stat + a couple git commands per directory on expand, (2) display — branch badge inline in the existing tree row, (3) refresh — pull endpoint reusing existing `pullRepo` from the git-backed workspace feature. The detection and pull share the same validation helper. No new auth concepts, no new workspace types, no new state management patterns. When extending, focus on "is this a read concern (already works) or a write concern (must gate through workspace read-only policy)?"

package/.next/standalone/.pi/ownership.json

@@ -1,3 +0,0 @@
-{
-  "claims": []
-}

package/.next/standalone/AGENTS.md

@@ -1,114 +0,0 @@
-# AGENTS.md
-
-Context for AI agents working in the **wiki-viewer** codebase.
-
-## What this is
-
-Local-or-remote file browser + editor. Run from terminal, starts a Next.js web server,
-navigate/read/edit any directory. Single-user no-auth by default; multi-user auth turns on
-once anyone signs up. Exposes an HTTP API for AI agents (two tiers) plus an MCP adapter.
-Git-aware: detects repos, shows branch/history/diff, supports git-backed read-only workspaces.
-Public shared-doc links via `/api/share`.
-
-Published to npm as `wiki-viewer`. CLI entry: `bin/wiki-viewer.js`.
-
-## Stack
-
-- **Next.js 16** (App Router, standalone output) + **React 19** + **TypeScript**
-- **Tailwind 3** + Radix UI + shadcn-style components (`src/components/ui`)
-- **TipTap 3** rich Markdown editor
-- **Better Auth** + **better-sqlite3** + **kysely** (pinned `0.28.5`) for auth/sessions
-- **Zustand** for client state (`src/stores`)
-- **chokidar** file watching, **proper-lockfile** write locks
-- Package manager: **pnpm** (workspace; do not use npm/yarn for installs)
-
-## Commands
-
-```bash
-pnpm install
-ROOT_DIR=~/notes pnpm dev      # dev server, hot reload
-pnpm dev:https                 # dev with experimental HTTPS
-pnpm build                     # production build (standalone)
-pnpm test                      # proof + auth suite (tsx node:test, 40 files / 180+ tests)
-```
-
-Test runner: `tsx --import ./src/tests/proof/preload.ts --test src/tests/proof/*.test.ts`.
-Single file: `tsx --import ./src/tests/proof/preload.ts --test src/tests/proof/<name>.test.ts`.
-
-## Layout
-
-```
-bin/wiki-viewer.js     CLI: arg parse, config, HTTPS proxy, systemd/launchd service, init wizard
-src/app/
-  api/agent/           Agent HTTP API — fs (tier1), files/events/sidecar (tier2),
-                       activity, register, admin, internal, settings
-  api/agents/          Public install/skill discovery endpoints
-  api/auth/            Better Auth handler
-  api/wiki/            File browser API (session-gated)
-  api/system/          System config API (session-gated)
-  api/share/           Public shared-doc links (token-gated)
-  api/owner/ api/upload/ api/assets/ api/app-proxy/
-  signin/  layout.tsx  page.tsx  manifest.ts
-src/components/
-  editor/              TipTap editor, proof-span, comment-pip, suggestion-card
-  ai-panel/            Agents, activity, install panel
-  wiki/ layout/ search/ ui/ auth-settings-sheet.tsx dir-picker.tsx
-src/lib/
-  proof/               Agent protocol core: ops-applier, registry, file-lock, raw-fs,
-                       collab-state, sidecar, blocks, block-refs, idempotency, rate-limit,
-                       audit, lease, mutex, activity, event-bus, pending, glob
-  auth/                Better Auth server+client, allowlist, CSRF
-  git.ts git-secrets.ts  System-git wrapper (provider-agnostic; token via GIT_ASKPASS),
-                       secret scanning. Backs git-history/diff/branch + read-only repo workspaces.
-  shared-docs/         Public shared-doc link store (db.ts)
-  workspaces.ts        Workspace registry (multi-root)
-  config.ts root-dir.ts app-runner.ts markdown/ search/ cabinets/ embeds/ google/
-src/stores/            Zustand stores
-src/middleware.ts      Cookie-presence gate for UI routes
-packages/wiki-viewer-mcp/   Standalone MCP adapter (own package.json, npm-published)
-docs/                  agent-collab-plan.md (tier-2 spec), file-vs-collab-authority.md
-agents/                Installable Agent Skill + bootstrap prompt
-```
-
-Import alias: `@/*` → `./src/*`.
-
-## Agent API model (the core domain)
-
-Two tiers share one auth/scope/lock spine:
-
-- **Tier 1 — raw filesystem** (`/api/agent/fs/*`): read/write/edit/list/search/move/delete for
-  all file types. Byte-accurate, audited. Overwrite requires `If-Match: <sha256>`.
-- **Tier 2 — Markdown collab** (`/api/agent/files/*`): block-ops wrapped in `<proof-span>`
-  provenance marks, comments, suggestions. Revision-checked, idempotent.
-
-**Working-vs-collaborating safety**: before editing a `.md` file, agents check the
-`X-Collab-State` response header (`active` / `tracked` / `untracked` / `not-markdown`).
-When `active` (human has it open), raw writes are rejected `409 COLLAB_ACTIVE` — use tier-2.
-This is enforced inside the write lock, not advisory. See `docs/file-vs-collab-authority.md`.
-
-**Auth**: Trust On First Use. Agent registers → owner approves in UI → one-shot token pickup.
-Bearer token + `X-Agent-Id` on every request. Only SHA-256 token hashes stored
-(`~/.wiki-viewer/agents.json`). Scopes: `paths` (glob), `ops` (`read`/`mutate`/`delete`).
-
-**Workspaces**: one server serves many root dirs, isolated. Agents target via `X-Workspace: <id>`
-header or `?ws=`. State (leases, locks, idempotency, sidecars, audit) namespaced per workspace.
-
-## State / runtime
-
-- User data dir: `~/.wiki-viewer/` — `auth.db` (WAL), `auth.secret` (0600), `agents.json`, `config.json`.
-- SQLite WAL is single-host only (not NFS / not clustered).
-- Config precedence: shell env > `config.json` `env` block > CLI-derived defaults.
-
-## Conventions / gotchas
-
-- Use pnpm. `kysely` is pinned to `0.28.5` via overrides — do not bump.
-- All state-changing `/api/wiki/*` and `/api/system/*` routes do CSRF Origin checks against
-  an allowlist (`WIKI_OWNER_HOSTS`). Cross-origin + cookie → `403`.
-- Production refuses to boot unless `BETTER_AUTH_URL` is an `https://` origin
-  (bypass with `WIKI_ALLOW_INSECURE=1` for dev/CI only).
-- Editor saves send `baseRevision`; stale → `409 STALE_REVISION`, editor reloads.
-- Agent paths reject traversal, symlink escape, and anything under `.proof/`.
-- When adding agent-API behavior, add/extend tests in `src/tests/proof/` and run `pnpm test`.
-- `AGENT_BEARER_TOKEN` (legacy single-secret) is dead — does nothing.
-- Git access uses the system `git` binary; tokens injected via `GIT_ASKPASS`, never in
-  process args / `.git/config` / `ps` output. `git-secrets.ts` scans for leaked secrets.