@soleone/factory 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +100 -2
- package/dist/cli.mjs +2074 -0
- package/dist/web/assets/geist-cyrillic-ext-wght-normal-DjL33-gN.woff2 +0 -0
- package/dist/web/assets/geist-cyrillic-wght-normal-BEAKL7Jp.woff2 +0 -0
- package/dist/web/assets/geist-latin-ext-wght-normal-DC-KSUi6.woff2 +0 -0
- package/dist/web/assets/geist-latin-wght-normal-BgDaEnEv.woff2 +0 -0
- package/dist/web/assets/geist-vietnamese-wght-normal-6IgcOCM7.woff2 +0 -0
- package/dist/web/assets/index-CJEcQ_Xz.js +79 -0
- package/dist/web/assets/index-CP8jYtPj.css +2 -0
- package/dist/web/favicon.svg +7 -0
- package/dist/web/index.html +44 -0
- package/package.json +74 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Soleone
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,101 @@
|
|
|
1
|
-
#
|
|
1
|
+
# factory
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Works a queue of coding tasks with headless `claude` and `pi`, until their usage limits run out. You pick tasks from what [workwork](https://github.com/Soleone/workwork) finds across your repos, or let auto mode keep the queue topped up. In the morning, the results list what each agent did, with the PR or issue it opened.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install -g @soleone/factory
|
|
7
|
+
factory serve # http://127.0.0.1:7040
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Needs node 22+, git, [workwork](https://github.com/Soleone/workwork) with `--json` support, and whichever of `claude` and `pi` you use, logged in.
|
|
11
|
+
|
|
12
|
+
## How it works
|
|
13
|
+
|
|
14
|
+
- **Repos** are yours on GitHub, cloned under `$SRC`, which is where workwork looks. The folder button right of the tabs lists the ones you haven't cloned yet, newest first, and clones one into a folder of `$SRC` you pick.
|
|
15
|
+
- **Jobs** are workwork candidates in the queue. Your picks always go first, in the order you give them; auto jobs follow. A job can name its agent, model and effort. Once an agent has started a job, the job stays with that agent.
|
|
16
|
+
- **Auto mode** only fills the queue: while the factory is on, it keeps up to 5 of its jobs per agent queued, cheapest attention first, with repos taking turns. It never re-queues a candidate that already had a job. You can limit it to some levels and plays.
|
|
17
|
+
- **The factory** is what works the queue, one worker per agent. With nothing to do it waits, and it picks up new jobs within seconds. Turning it on starts a **run** with its own agents, models, efforts, limit and end time, defaulting to the settings.
|
|
18
|
+
- **Limits:** a limit of 1 (the default) stops an agent at its first usage-limit hit, so only the current allowance gets used. A limit of 2 waits for one reset and stops at the second hit. "None" always waits for the reset, which it logs. Once every agent has stopped, the factory turns itself off. Three quick failures in a row also count as a limit hit, so a broken login can't burn through the queue.
|
|
19
|
+
- **Failures:** a failed or timed-out job gets one more try by the same agent. After that it waits for you to retry it.
|
|
20
|
+
|
|
21
|
+
## Reviewing results
|
|
22
|
+
|
|
23
|
+
Each result links the PR or issue the agent opened. From the page you can read a PR's description and diff, merge it, rebase it onto its base when GitHub reports conflicts, or close it. Rebasing never guesses: if git stops on a conflict, nothing is pushed and the page lists the files.
|
|
24
|
+
|
|
25
|
+
**Merge train:** select several results and merge them in one go. PRs merge one after another per repo, since each merge moves the base under the next one; repos go in parallel. The train waits for checks, rebases a PR that conflicts, and skips one it can't merge, with the reason. When a rebase stops on real conflicts, a job to resolve them goes to the front of the queue, so an agent picks it up on the next run.
|
|
26
|
+
|
|
27
|
+
## Live Agent
|
|
28
|
+
|
|
29
|
+
Live Agent, the robot button right of the tabs, is a chat with an agent about what to queue. It reads the candidates, the queue and past results, proposes a few jobs that won't step on each other, and adds them through the CLI once you agree. It never turns the factory on, merges or closes PRs, or changes your repos. That is an instruction to the agent, not a sandbox: it has a shell, like the agents doing jobs. Results that failed, or that the train skipped, have an **Ask** button that starts the chat with the question already written.
|
|
30
|
+
|
|
31
|
+
Settings > Live Agent picks the agent (Claude Code or Pi), its model and effort. The same model and effort pickers serve runs. Model choices are short lists: Pi's scoped models (`enabledModels` in Pi's settings, the ones Ctrl+P cycles through), and Claude Code's current models (opus, sonnet, fable, haiku). The efforts on offer are the chosen model's. When one of Pi's extensions asks something mid-chat, the page shows the question. The chat survives a restart of `factory serve`: the page shows it again and the agent resumes its own session, so it still knows what was said. New chat starts over.
|
|
32
|
+
|
|
33
|
+
## Commands
|
|
34
|
+
|
|
35
|
+
The page and the CLI do the same things on the same state; `serve` is only an interface, and the factory runs without it.
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
factory start [run options] # turn on, in the background (factory run: in the foreground)
|
|
39
|
+
factory stop # turn off; jobs in progress go back to the queue
|
|
40
|
+
factory status # on or off, what each agent does, the queue
|
|
41
|
+
factory add <id>... [--repo DIR] [--agent NAME] [--model M] [--effort E]
|
|
42
|
+
factory remove <job> | retry <job>
|
|
43
|
+
factory auto on|off
|
|
44
|
+
factory report [--all] # the last run (or every run): outcome, agent, PR/issue link or log
|
|
45
|
+
factory serve [--port 7040] [--host 127.0.0.1]
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Run options: `--agents claude,pi`, `--limit N|none`, `--until HH:MM` (start nothing new after), `--model claude=opus`, `--effort pi=high` (claude's `--effort`, pi's `--thinking`), `--timeout MIN`.
|
|
49
|
+
|
|
50
|
+
`serve` listens on 127.0.0.1. Anyone who can reach it can queue jobs and turn the factory on, and the agents run with full permissions, so it amounts to running commands on your machine. Reach it from a phone through something like `tailscale serve`, not with `--host 0.0.0.0` on a network you don't trust.
|
|
51
|
+
|
|
52
|
+
## Worktrees
|
|
53
|
+
|
|
54
|
+
Each agent gets one worktree per repo, under the state folder, reused from job to job so installed dependencies survive. Before every job it's reset to a freshly fetched `origin/HEAD`, and untracked files are removed but ignored ones are kept. Your own checkout is never touched. If an agent leaves commits that aren't on a remote, or uncommitted changes, they're saved to a branch `factory/<job>-<attempt>` in the repo, and the result says so.
|
|
55
|
+
|
|
56
|
+
## State
|
|
57
|
+
|
|
58
|
+
In `$DATA/apps/factory/` when `DATA` is set, otherwise `~/.local/share/factory/`:
|
|
59
|
+
|
|
60
|
+
- `settings.json`: registered agents with their model and effort, the agent Live Agent uses, limit, until, timeout, auto mode (on, levels, plays, repos)
|
|
61
|
+
- `jobs.jsonl`: append-only events (add, remove, move, start, attempt, requeue, retry), so the CLI, the factory and the page never overwrite each other
|
|
62
|
+
- `candidates.json`: the cached `workwork --all --json`, which takes minutes; refreshed from the page, or by auto mode when older than 6 hours
|
|
63
|
+
- `runs/<run>/<job>-<attempt>/`: `prompt.md` and `agent.log`
|
|
64
|
+
- `chat.json`, `chat.jsonl`, `chat-sessions/`: the Live Agent session, what the page shows, and Pi's session files (Claude Code keeps its own)
|
|
65
|
+
- `worktrees/<agent>/<repo>/`
|
|
66
|
+
- `status.json`, `factory.pid`, `factory.log`: the current run
|
|
67
|
+
|
|
68
|
+
## Why not an LLM loop
|
|
69
|
+
|
|
70
|
+
This replaces an assistant that ran the night from inside chat turns. It stopped whenever a turn ended, built its own queue, guards and "authorization" out of prompts, then got blocked by them, and rewrote its own instructions after every failure. The tasks themselves went fine. So here the loop is plain code, and a model only ever does one task, as a child process that exits. Nothing a model says decides what runs next, who gets it, or whether to keep going.
|
|
71
|
+
|
|
72
|
+
## Development
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
pnpm install
|
|
76
|
+
pn dev
|
|
77
|
+
vp check && vp test run && kit check
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The page is built on the [kit](https://github.com/Soleone/kit) web stack: Vite+, React, shadcn base-nova and the @soleone theme. `src/backend/` holds the CLI, the factory and the server; `src/` the page. `pn dev` runs Vite with hot reload at http://localhost:7040 in front of `factory serve` on 7041, which restarts when `src/backend/` changes. It uses your real state folder, so Turn on starts real agents. `pn build` bundles the CLI to `dist/cli.mjs` and the page to `dist/web/`.
|
|
81
|
+
|
|
82
|
+
### Try the UI with dummy data
|
|
83
|
+
|
|
84
|
+
Run `pnpm dev:demo` and open [factory (demo)](http://localhost:7042). Browse sample candidates, reorder the queue, retry a failed job, review sample PRs, or try the run and settings controls. Turn on shows simulated workers without executing any jobs.
|
|
85
|
+
|
|
86
|
+
The demo does not start `factory serve`, call `workwork` or GitHub, or read or write your real Factory state. Changes are shared across tabs and reset when you restart the demo server.
|
|
87
|
+
|
|
88
|
+
### Release
|
|
89
|
+
|
|
90
|
+
From `main` with a clean working tree, authenticated Git push access, and pnpm logged in to npm (`pn whoami`):
|
|
91
|
+
|
|
92
|
+
```sh
|
|
93
|
+
pn release # choose patch, minor or major, then confirm each step
|
|
94
|
+
pn release --dry-run # preview without changing files, publishing or pushing
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
With Vite+, `pn` is shorthand for `pnpm`. The release command asks for the version, updates `CHANGELOG.md` from conventional commits, commits and tags `vX.Y.Z`, and pushes. Factory publishes `@soleone/factory` to npm locally rather than building native apps in Actions. Checks and tests run before releasing; `prepublishOnly` builds the CLI before publishing. Dry runs skip these hooks, so run the development checks above separately.
|
|
98
|
+
|
|
99
|
+
## License
|
|
100
|
+
|
|
101
|
+
MIT
|