spoon/README.md

<p align="center">
  <img src="apps/next/public/favicon.png" alt="Spoon logo" width="96" height="96" />
</p>

<h1 align="center">Spoon</h1>

<p align="center">
  <strong>Fork freely & keep them all intimately close to upstream.</strong>
</p>

<p align="center">
  Spoon is a self-hostable fork maintenance cockpit built around managed forks,
  durable maintenance threads, and OpenCode-powered workspaces.
</p>

<p align="center">
  <a href="#what-this-is">What this is</a>
  ·
  <a href="#product-model">Product model</a>
  ·
  <a href="#architecture">Architecture</a>
  ·
  <a href="#environment-reference">Environment</a>
</p>

---

## What This Is

Spoon is a private, actively evolving project for making forks less lonely to
maintain.

Forking a project is easy. Keeping that fork close to upstream after you add
custom changes is the hard part. Spoon treats a fork as an ongoing relationship:
it watches upstream, understands fork-only commits, automatically syncs clean
drift when it can, and opens a durable **Thread** when a decision needs context
or code.

The application is currently GitHub-first. Future provider-neutral fields exist
in the data model, but GitHub is the active automation surface today.

## Highlights

- **Managed forks, called Spoons**  
  Track upstream metadata, fork metadata, clone URLs, extra remotes, sync
  cadence, production-ref strategy, fork-only commits, and pull requests.

- **Thread-first maintenance**  
  Upstream updates, conflict review, ignore decisions, user-requested work,
  worker output, and draft PR handoff all live inside Threads.

- **Clean drift auto-sync**  
  If upstream moves and the fork has no custom commits, Spoon can fast-forward
  the fork without creating busywork.

- **Custom forks get context**  
  If the fork has custom commits, Spoon creates a maintenance thread rather than
  pretending the update is trivial.

- **Effective drift**  
  Spoon keeps raw GitHub drift visible while also tracking ignored upstream
  changes so irrelevant commits do not keep a fork permanently actionable.

- **OpenCode workspaces**  
  Agent work happens in an isolated workspace with a file tree, browser editor,
  diff viewer, command panel, logs, artifacts, and draft PR actions.

- **User-owned providers and secrets**  
  AI provider profiles, Codex/OpenCode auth, and per-Spoon project secrets are
  encrypted. Secrets are redacted from logs and refused from commits when
  materialized into env files.

- **Draft PR handoff**  
  Code changes become branches and draft pull requests. Spoon does not
  auto-merge custom forks behind the user's back.

## Product Model

<details open>
<summary><strong>Spoons</strong></summary>

A **Spoon** is a managed fork. It records the upstream project, the fork
repository, default branches, sync policy, extra remotes, current drift, cached
commits, cached pull requests, secrets, and agent settings.

Spoons are the durable project-level objects. They answer:

- What did I fork?
- Where does my fork live?
- How far has it drifted?
- Which commits are mine?
- Which upstream changes matter?
- What threads or PRs are open?

</details>

<details open>
<summary><strong>Threads</strong></summary>

A **Thread** is the durable place where Spoon talks about maintenance work.
Threads can be created by a user or by the system.

Common thread sources:

- `user_request`: user asks Spoon to change a fork.
- `upstream_update`: upstream moved and the fork needs review.
- `merge_conflict`: a sync conflict needs context or code.
- `manual_review`: user explicitly asks for a review.
- `system`: internal maintenance coordination.

Threads hold messages, status, outcomes, related sync runs, related jobs,
workspace links, draft PR links, and ignored upstream decisions.

</details>

<details open>
<summary><strong>Maintenance decisions</strong></summary>

Spoon's maintenance policy is intentionally conservative:

| Situation                                  | Default action                        |
| ------------------------------------------ | ------------------------------------- |
| No fork-only commits and upstream is ahead | Auto-sync                             |
| Fork-only commits and upstream is ahead    | Create a maintenance thread           |
| Merge conflicts                            | Open or continue a workspace thread   |
| Irrelevant upstream changes                | Record an intentional ignore decision |
| Agent/code changes                         | Open a draft PR                       |

The goal is to keep forks close without hiding risk or skipping review when
custom work exists.

</details>

<details>
<summary><strong>OpenCode workspaces</strong></summary>

Spoon's optional agent worker is designed to run outside Convex actions. The
worker claims queued jobs, clones the current GitHub fork, creates a branch,
starts an isolated workspace, and exposes workspace operations to the Next app
through server-only API proxies.

Workspace capabilities:

- browse repository files
- edit files in a browser editor
- use optional Vim keybindings
- inspect diffs
- send thread messages to the agent
- run configured commands
- store logs and artifacts
- push a branch
- open a draft PR

The browser never receives worker tokens and never talks directly to the worker
or job container.

</details>

## Architecture

<details open>
<summary><strong>Workspace layout</strong></summary>

```txt
.
├── apps
│   ├── next              # Next.js 16 web app and primary Spoon UI
│   ├── agent-worker      # Optional OpenCode workspace / draft PR worker
│   └── expo              # Expo companion app scaffold
├── packages
│   ├── backend           # Convex backend package
│   │   └── convex        # Schema, functions, auth, HTTP routes
│   └── ui                # Shared shadcn-based UI components
├── tools                 # Shared lint, format, Tailwind, TS, Vitest config
├── docker                # Compose files and worker/job Dockerfiles
└── scripts               # Env, Convex, codegen, database, and CI helpers
```

</details>

<details>
<summary><strong>Core tables</strong></summary>

| Table                    | Purpose                                                   |
| ------------------------ | --------------------------------------------------------- |
| `spoons`                 | Managed fork records                                      |
| `threads`                | Durable maintenance and work conversations                |
| `threadMessages`         | Messages inside threads                                   |
| `syncRuns`               | Upstream checks, sync attempts, and maintenance decisions |
| `ignoredUpstreamChanges` | Intentional ignore records that affect effective drift    |
| `gitConnections`         | Git provider connection metadata                          |
| `spoonRepositoryStates`  | Latest cached upstream/fork state                         |
| `spoonCommits`           | Cached upstream and fork-only commits                     |
| `spoonPullRequests`      | Cached fork/upstream pull requests                        |
| `spoonSecrets`           | Encrypted per-Spoon environment variables                 |
| `spoonAgentSettings`     | Per-Spoon runtime, branch, command, and env-file settings |
| `aiProviderProfiles`     | Encrypted provider/auth profiles used by OpenCode         |
| `agentJobs`              | Worker-executed workspace jobs and PR lifecycle           |
| `agentJobEvents`         | Append-only worker event log                              |
| `agentJobArtifacts`      | Diffs, summaries, command output, PR body drafts          |
| `agentWorkspaceChanges`  | Recorded user, agent, and command file changes            |

</details>

<details>
<summary><strong>Important routes</strong></summary>

| Route                             | Purpose                                 |
| --------------------------------- | --------------------------------------- |
| `/`                               | Public product landing page             |
| `/dashboard`                      | Maintenance overview                    |
| `/spoons`                         | Managed fork list                       |
| `/spoons/new`                     | Manual/GitHub Spoon creation            |
| `/spoons/[spoonId]`               | Spoon detail dashboard                  |
| `/spoons/[spoonId]/agent/[jobId]` | Interactive workspace                   |
| `/threads`                        | Global thread queue                     |
| `/threads/[threadId]`             | Thread detail                           |
| `/settings/profile`               | User profile settings                   |
| `/settings/integrations`          | GitHub and service integration settings |
| `/settings/ai-providers`          | AI/OpenCode provider profiles           |

Legacy `/updates` and `/agents` routes redirect into `/threads`.

</details>

## Mobile App

<details open>
<summary><strong>Current Expo scope</strong></summary>

`apps/expo` is the mobile Spoon client. It is designed to mirror the core web
product without exposing worker internals or trying to turn a phone into the
primary code-editing surface.

The mobile app currently supports:

- password, GitHub, and Authentik sign-in
- Dashboard, Spoons, Threads, Workspace Review, and Settings tabs/screens
- manual Spoon creation and GitHub-assisted repository tracking
- Spoon detail views for overview, upstream commits, fork-only commits, PRs,
  threads, settings, clone URLs, and additional remotes
- Spoon maintenance settings, agent settings, encrypted secrets, and bulk
  `.env` paste import
- thread list/detail, message composer, resolve/cancel actions, and workspace
  review links
- GitHub integration status and repository listing
- AI provider profile management, including Codex/OpenCode auth JSON
- read-only workspace review for job status, messages, diffs, events,
  artifacts, and draft PR links

The mobile app intentionally does not currently support:

- live workspace file browsing/editing
- mobile command execution
- direct mobile calls to the agent worker HTTP API
- mobile access to worker/container tokens
- long-running app preview stacks
- production app-store/EAS release flow

Mobile workspace editing is deferred until worker authorization and mobile
editor UX are designed explicitly. For now, the phone is a strong review and
control surface; the browser remains the code workspace.

</details>

<details>
<summary><strong>Expo validation</strong></summary>

Useful mobile checks:

```sh
bun --filter @spoon/expo lint
bun --filter @spoon/expo typecheck
bun --filter @spoon/expo test:unit
bun --filter @spoon/expo test:component
```

The Expo unit tests cover pure utilities such as `.env` parsing and formatting.
The component tests use a lightweight React Native mock layer to exercise shared
mobile controls, higher-value forms, and route smoke renders without booting a
native simulator.

</details>

## Environment Reference

This project is currently private, so this section is a reference for what the
application expects rather than public setup documentation.

<details open>
<summary><strong>Public Next variables</strong></summary>

| Variable                          | Used for                                    |
| --------------------------------- | ------------------------------------------- |
| `NEXT_PUBLIC_SITE_URL`            | Canonical Spoon web URL                     |
| `NEXT_PUBLIC_CONVEX_URL`          | Convex client URL                           |
| `NEXT_PUBLIC_DEPLOYMENT_URL`      | Convex dashboard/deployment URL when needed |
| `NEXT_PUBLIC_PLAUSIBLE_URL`       | Plausible analytics endpoint                |
| `NEXT_PUBLIC_SENTRY_DSN`          | Browser Sentry DSN                          |
| `NEXT_PUBLIC_SENTRY_URL`          | Sentry instance URL                         |
| `NEXT_PUBLIC_SENTRY_ORG`          | Sentry organization                         |
| `NEXT_PUBLIC_SENTRY_PROJECT_NAME` | Sentry project name                         |

</details>

<details>
<summary><strong>Auth and email</strong></summary>

| Variable                | Used for                      |
| ----------------------- | ----------------------------- |
| `SITE_URL`              | Convex Auth site URL          |
| `JWT_PRIVATE_KEY`       | Convex Auth signing key       |
| `JWKS`                  | Convex Auth JWKS              |
| `AUTH_AUTHENTIK_ID`     | Authentik OAuth client ID     |
| `AUTH_AUTHENTIK_SECRET` | Authentik OAuth client secret |
| `AUTH_AUTHENTIK_ISSUER` | Authentik issuer URL          |
| `AUTH_GITHUB_ID`        | GitHub OAuth client ID        |
| `AUTH_GITHUB_SECRET`    | GitHub OAuth client secret    |
| `USESEND_API_KEY`       | UseSend API key               |
| `USESEND_URL`           | UseSend API URL               |
| `USESEND_FROM_EMAIL`    | Transactional email sender    |

</details>

<details>
<summary><strong>GitHub App</strong></summary>

| Variable                     | Used for                           |
| ---------------------------- | ---------------------------------- |
| `GITHUB_APP_ID`              | GitHub App ID                      |
| `GITHUB_APP_CLIENT_ID`       | GitHub App OAuth client ID         |
| `GITHUB_APP_CLIENT_SECRET`   | GitHub App OAuth client secret     |
| `GITHUB_APP_PRIVATE_KEY`     | GitHub App PEM private key         |
| `GITHUB_APP_WEBHOOK_SECRET`  | GitHub webhook verification secret |
| `GITHUB_APP_SLUG`            | GitHub App slug                    |
| `GITHUB_APP_INSTALLATION_ID` | Default/local installation ID      |
| `GITHUB_APP_OWNER`           | Default/local installation owner   |

</details>

<details>
<summary><strong>Convex, storage, and runtime</strong></summary>

| Variable                            | Used for                                        |
| ----------------------------------- | ----------------------------------------------- |
| `CONVEX_SELF_HOSTED_URL`            | Self-hosted Convex API URL                      |
| `CONVEX_SELF_HOSTED_ADMIN_KEY`      | Admin key for deploying/syncing Convex          |
| `CONVEX_CLOUD_ORIGIN`               | Convex backend origin                           |
| `CONVEX_SITE_ORIGIN`                | Convex site-function origin                     |
| `CONVEX_SITE_URL`                   | Site URL seen by Convex Auth                    |
| `POSTGRES_URL`                      | Convex storage database URL                     |
| `SPOON_ENCRYPTION_KEY`              | Encryption key for stored secrets/provider auth |
| `SPOON_WORKER_TOKEN`                | Worker token for Convex worker mutations        |
| `SPOON_AGENT_WORKER_URL`            | Internal worker HTTP URL used by Next           |
| `SPOON_AGENT_WORKER_HTTP_PORT`      | Worker HTTP port                                |
| `SPOON_AGENT_WORKER_INTERNAL_TOKEN` | Server-only token for Next-to-worker proxy      |
| `SPOON_AGENT_JOB_IMAGE`             | Agent job container image                       |
| `SPOON_AGENT_RUNTIME`               | Runtime mode, currently Docker/Podman-oriented  |
| `SPOON_AGENT_MAX_CONCURRENT_JOBS`   | Worker concurrency limit                        |
| `SPOON_AGENT_JOB_TIMEOUT_MS`        | Job timeout                                     |
| `SPOON_AGENT_WORKDIR`               | Worker work directory                           |
| `SPOON_AGENT_NETWORK`               | Optional job container network                  |

</details>

<details>
<summary><strong>Deployment and observability</strong></summary>

| Variable                | Used for                          |
| ----------------------- | --------------------------------- |
| `NODE_ENV`              | Runtime environment               |
| `SENTRY_AUTH_TOKEN`     | Sentry source map/upload auth     |
| `REDACT_LOGS_TO_CLIENT` | Convex log redaction setting      |
| `DISABLE_BEACON`        | Self-hosted Convex beacon setting |
| `DO_NOT_REQUIRE_SSL`    | Self-hosted Convex SSL behavior   |
| `CI_ENV_FILE`           | CI-provided env file path         |

</details>

## Current Status

<details open>
<summary><strong>Implemented</strong></summary>

- Thread-first Next.js product shell
- GitHub App connection and fork creation foundation
- GitHub drift refresh, commit cache, PR cache, and sync-run history
- Effective drift and ignored upstream change records
- Global Threads page and Spoon-scoped Threads tab
- OpenCode-oriented agent worker and browser workspace foundation
- Monaco editor with optional Vim mode
- Diff viewer, command panel, worker logs, and artifacts
- Encrypted Spoon secrets and bulk `.env` import
- Encrypted AI provider profiles, including Codex/OpenCode auth support
- Authentik, GitHub, and password auth through Convex Auth
- Self-hosted Convex/Postgres deployment model

</details>

<details>
<summary><strong>Intentionally not done yet</strong></summary>

- Autonomous merging for custom/diverged forks
- Non-GitHub provider automation
- Pushing agent branches to additional remotes
- Long-running preview stacks for arbitrary forked projects
- Direct browser access to worker containers
- Public self-hosting setup documentation
- Production mobile release flow

</details>

## Notes

Spoon is built for a very specific maintenance problem: "I want to fork this
project, but I do not want to permanently become its maintenance team."

The current product direction is to make that maintenance visible, threaded,
reviewable, and increasingly automated where it is safe. Clean forks can stay
close automatically. Custom forks get context, workspace help, and draft PRs.