Chris Farhood
ebc249d0b3
Build: Production / build (push) Failing after 10m22s
The overlay lives on dev (canonical) and local, not master. Master is now a pure mirror of upstream. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
80 lines
3.9 KiB
Markdown
80 lines
3.9 KiB
Markdown
# Paperclip Fork — Project Context
|
|
|
|
This is a fork of [paperclipai/paperclip](https://github.com/paperclipai/paperclip).
|
|
Fork repo: https://git.farh.net/farhoodlabs/paperclip
|
|
|
|
## Branch Model
|
|
|
|
| Branch | Purpose |
|
|
|---|---|
|
|
| `master` | Pure mirror of `upstream/master`. No fork-specific files in the tree. Sync via `git push origin upstream/master:master --force-with-lease`. |
|
|
| `local` | **Default branch.** Assembled automatically by `assemble-local.yml` (defined on `dev`) on every `master` push. Contains: upstream + fork Dockerfile/workflows + all pending upstream PR cherry-picks. Builds `git.farh.net/farhoodlabs/paperclip`. |
|
|
| `dev` | Development branch and canonical home of the `.farhoodlabs/` overlay and the `assemble-local.yml` action. Based on upstream/master. Builds `git.farh.net/farhoodlabs/paperclip-dev` on every push. |
|
|
| PR branches | `skill-pat-feature`, `skill-scan-refresh`, `feat/company-portability-complete` — open PRs to upstream, never rebase onto master/local. |
|
|
|
|
**Never commit directly to `local`** — it is fully regenerated by the assemble action and any direct commits will be overwritten.
|
|
|
|
## Fork Overlay (`.farhoodlabs/`)
|
|
|
|
Files committed to `.farhoodlabs/` on `dev` (the canonical source) that get copied into position on `local` by the assemble action:
|
|
|
|
```
|
|
.farhoodlabs/
|
|
CLAUDE.md → CLAUDE.md (repo root)
|
|
Dockerfile → Dockerfile
|
|
.github/workflows/build-prod.yml → .github/workflows/build-prod.yml
|
|
.github/workflows/build-dev.yml → .github/workflows/build-dev.yml
|
|
```
|
|
|
|
The fork's Dockerfile production stage additions over upstream: `kubectl`, `kubeseal`, `uv`/`uvx`, `forgejo-cli` (`fj`, `fj-ex`, `fgj`), `nano`, `vim`.
|
|
|
|
To modify fork-specific files, edit them in `.farhoodlabs/` on `dev` and push. The assemble action will apply them to `local` on the next `master` push (or trigger it manually via `workflow_dispatch`).
|
|
|
|
## Pending Upstream PRs (included in `local`)
|
|
|
|
These are cherry-picked/squashed onto `local` by the assemble action. When upstream merges one, remove its entry from `assemble-local.yml`.
|
|
|
|
| PR | Branch | Method | Notes |
|
|
|---|---|---|---|
|
|
| #3237 | `skill-pat-feature` | cherry-pick | GitHub PAT support for private skill repos |
|
|
| #3351 | `skill-scan-refresh` | cherry-pick (exclude: skill-pat-feature) | Rebased onto skill-pat-feature |
|
|
| #3987 | `feat/company-portability-complete` | squash | Secrets export/import; squashed to bypass intra-PR merge commits |
|
|
|
|
## Common Tasks
|
|
|
|
### Sync upstream into master
|
|
```bash
|
|
git fetch upstream
|
|
git push origin upstream/master:master --force-with-lease
|
|
# assemble-local.yml triggers automatically and rebuilds local
|
|
```
|
|
|
|
### Add a new pending PR to local
|
|
Edit `.github/workflows/assemble-local.yml` on `dev`:
|
|
- Simple PR (clean commits, no merge commits): add to `PR_CHERRY_PICK`
|
|
- Complex PR (has merge commits mixed in): add to `PR_SQUASH`
|
|
- If the branch was rebased onto another PR branch: use `exclude:base-branch`
|
|
|
|
### Remove a PR after upstream merges it
|
|
Delete its entry from `PR_CHERRY_PICK` or `PR_SQUASH` in `assemble-local.yml` on `dev`.
|
|
|
|
### Submit a new PR to upstream
|
|
Branch from `upstream/master` (not from `local` or `master`):
|
|
```bash
|
|
git fetch upstream
|
|
git checkout -b feat/my-feature upstream/master
|
|
```
|
|
|
|
### Modify the fork Dockerfile
|
|
Edit `.farhoodlabs/Dockerfile` on `dev`. Only modify the production stage — keep base/deps/build stages identical to upstream so diffs are minimal and upstream changes apply cleanly.
|
|
|
|
## Deployment
|
|
|
|
Paperclip runs in Kubernetes, not locally. Use `kubectl` to access it. The production image is `git.farh.net/farhoodlabs/paperclip:latest`.
|
|
|
|
## Key Files
|
|
|
|
- `.github/workflows/assemble-local.yml` — assembles `local` branch; edit this to manage pending PRs
|
|
- `.farhoodlabs/` — fork overlay; all fork-specific files live here on `dev` (canonical) and are also kept in sync on `local`
|
|
- `server/package.json` — has an adapter-utils workspace vs canary hack that needs fixing eventually
|