@forloop-cc/forloop-cli 0.2.1

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.
Files changed (5) hide show
  1. package/ERRORS.md +260 -0
  2. package/README.md +636 -0
  3. package/dist/forloop.mjs +2440 -0
  4. package/install.sh +90 -0
  5. package/package.json +52 -0
package/ERRORS.md ADDED
@@ -0,0 +1,260 @@
1
+ # ForLoop CLI Error Reference
2
+
3
+ This document lists all error scenarios and the messages users will see.
4
+
5
+ ## Exit Codes
6
+
7
+ | Code | Meaning |
8
+ |------|---------|
9
+ | 0 | Success |
10
+ | 1 | General error |
11
+ | 2 | Usage error (invalid arguments) |
12
+ | 3 | Authentication error |
13
+ | 4 | Quota error |
14
+ | 5 | Timeout |
15
+ | 6 | Network error |
16
+ | 7 | API error |
17
+ | 10 | Content filter |
18
+ | 130 | Interrupted (Ctrl+C / SIGINT) |
19
+
20
+ ---
21
+
22
+ ## Auth Commands
23
+
24
+ ### `forloop auth login`
25
+
26
+ | Scenario | Error Message |
27
+ |---|---|
28
+ | `--api-key` not provided | `Error: --api-key is required and must start with "floop_"` |
29
+ | Token does not start with `floop_` | `Error: --api-key is required and must start with "floop_"` |
30
+ | Token validation failed | `Invalid token: <validation error>` |
31
+
32
+ ### `forloop auth status`
33
+
34
+ | Scenario | Error Message |
35
+ |---|---|
36
+ | No token configured | `Not authenticated` + `Run: forloop auth login --api-key <token>` |
37
+ | Token configured but invalid format | `Token: floop_xx...xxxx` + `Format: invalid` + `Error: <reason>` |
38
+
39
+ ### `forloop auth logout`
40
+
41
+ No error scenarios — silently clears the token.
42
+
43
+ ---
44
+
45
+ ## Sprint Commands
46
+
47
+ ### `forloop sprint get`
48
+
49
+ | Scenario | Error Message |
50
+ |---|---|
51
+ | No sprint ID resolved | `Error: No sprint ID resolved. Use --id, set FORLOOP_SPRINT_ID, or use a sprint-XXX branch.` |
52
+ | Sprint not found (404) | `ForLoop API GET /api/opencode/sprints/<id> failed: 404 Not Found` |
53
+
54
+ ### `forloop sprint list`
55
+
56
+ | Scenario | Error Message |
57
+ |---|---|
58
+ | No sprints found | `No sprints found.` |
59
+
60
+ ### `forloop sprint create`
61
+
62
+ | Scenario | Error Message |
63
+ |---|---|
64
+ | Missing `--title`, `--start-date`, or `--end-date` | `Error: --title, --start-date, and --end-date are required` |
65
+
66
+ ### `forloop sprint update`
67
+
68
+ | Scenario | Error Message |
69
+ |---|---|
70
+ | `--id` not provided | `Error: --id is required` |
71
+ | No fields to update | `Error: at least one field to update is required` |
72
+
73
+ ### `forloop sprint delete`
74
+
75
+ | Scenario | Error Message |
76
+ |---|---|
77
+ | `--confirm` not provided | `Error: --confirm is required to permanently delete a sprint.` |
78
+ | Sprint not found | `ForLoop API DELETE /api/opencode/sprints/<id> failed: 404 Not Found` |
79
+
80
+ ---
81
+
82
+ ## Story Commands
83
+
84
+ ### `forloop story create`
85
+
86
+ | Scenario | Error Message |
87
+ |---|---|
88
+ | Missing `--title` or `--sprint` | `Error: --title and --sprint are required` |
89
+ | Invalid `--type` value | `Error: --type must be "basic-task" or "basic-note"` |
90
+ | Template not found | `Error: Template "<slug>" not found` |
91
+
92
+ ### `forloop story get`
93
+
94
+ | Scenario | Error Message |
95
+ |---|---|
96
+ | `--id` not provided | `Error: --id is required` |
97
+ | Story not found (403) | `ForLoop API GET /api/opencode/stories/<id> failed: 403 Forbidden` |
98
+
99
+ ### `forloop story update`
100
+
101
+ | Scenario | Error Message |
102
+ |---|---|
103
+ | `--id` not provided | `Error: --id is required` |
104
+ | No fields to update | `Error: at least one field to update is required` |
105
+
106
+ ### `forloop story delete`
107
+
108
+ | Scenario | Error Message |
109
+ |---|---|
110
+ | `--confirm` not provided | `Error: --confirm is required to permanently delete a story.` |
111
+
112
+ ---
113
+
114
+ ## Organization Commands
115
+
116
+ ### `forloop org get`
117
+
118
+ | Scenario | Error Message |
119
+ |---|---|
120
+ | `--id` not provided | `Error: --id is required` |
121
+
122
+ ### `forloop org create`
123
+
124
+ | Scenario | Error Message |
125
+ |---|---|
126
+ | `--name` not provided | `Error: --name is required` |
127
+ | Free tier (no orgs allowed) | API returns quota/tier error |
128
+
129
+ ### `forloop org update`
130
+
131
+ | Scenario | Error Message |
132
+ |---|---|
133
+ | `--id` not provided | `Error: --id is required` |
134
+
135
+ ---
136
+
137
+ ## Agent Commands
138
+
139
+ ### `forloop agent developer-sprint`
140
+
141
+ | Scenario | Error Message |
142
+ |---|---|
143
+ | `--sprint` not provided | `Error: --sprint is required` |
144
+ | Sprint not found | API error with 404 |
145
+
146
+ ### `forloop agent history`
147
+
148
+ | Scenario | Error Message |
149
+ |---|---|
150
+ | No history found | `No conversation history found.` |
151
+
152
+ ### `forloop agent developer-status`
153
+
154
+ | Scenario | Error Message |
155
+ |---|---|
156
+ | No sprint resolved | `Error: No sprint ID resolved.` |
157
+ | No active task | `No active developer task.` + sprint progress |
158
+
159
+ ---
160
+
161
+ ## User Commands
162
+
163
+ ### `forloop org quotas`
164
+
165
+ | Scenario | Error Message |
166
+ |---|---|
167
+ | `--org-id` not provided | `Error: --org-id is required` |
168
+
169
+ ---
170
+
171
+ ## File Commands
172
+
173
+ ### `forloop file upload`
174
+
175
+ | Scenario | Error Message |
176
+ |---|---|
177
+ | `--path` or `--sprint` not provided | `Error: --path and --sprint are required` |
178
+ | File not found at `--path` | `Error: File not found: <path>` |
179
+ | Upload failed (S3 presigned URL) | `Error: Upload failed (<status>)` |
180
+
181
+ ### `forloop file list`
182
+
183
+ | Scenario | Error Message |
184
+ |---|---|
185
+ | `--sprint` not provided | `Error: --sprint is required` |
186
+ | No files found | `No files found.` |
187
+
188
+ ### `forloop file delete`
189
+
190
+ | Scenario | Error Message |
191
+ |---|---|
192
+ | `--confirm` not provided | `Error: --confirm is required.` |
193
+
194
+ ### `forloop file download`
195
+
196
+ | Scenario | Error Message |
197
+ |---|---|
198
+ | `--id` not provided | `Error: --id is required` |
199
+
200
+ ---
201
+
202
+ ## Folder Commands
203
+
204
+ ### `forloop folder create`
205
+
206
+ | Scenario | Error Message |
207
+ |---|---|
208
+ | `--title` or `--sprint` not provided | `Error: --title and --sprint are required` |
209
+
210
+ ---
211
+
212
+ ## Sync Commands
213
+
214
+ ### `forloop sync s3-to-local`
215
+
216
+ | Scenario | Error Message |
217
+ |---|---|
218
+ | No sprint resolved | `Error: No sprint ID resolved.` |
219
+
220
+ ### `forloop sync local-to-s3`
221
+
222
+ | Scenario | Error Message |
223
+ |---|---|
224
+ | `--path` not provided | `Error: --path is required` |
225
+ | File not found | `Error: File not found: <path>` |
226
+
227
+ ---
228
+
229
+ ## Global Errors (All Commands)
230
+
231
+ ### Authentication
232
+
233
+ | Scenario | Error Message | Exit Code |
234
+ |---|---|---|
235
+ | No token configured | `Error: No ForLoop API token configured.` + how-to-fix | 3 |
236
+ | Token invalid (API 401) | `ForLoop API <method> <path> failed: 401 Unauthorized` | 3 |
237
+
238
+ ### Network & API
239
+
240
+ | Scenario | Error Message | Exit Code |
241
+ |---|---|---|
242
+ | Network failure | `ForLoop API <method> <path> failed: ...` | 6 |
243
+ | Request timeout | `ForLoop API <method> <path> failed: ...` | 5 |
244
+ | API 429 (rate limit) | `ForLoop API <method> <path> failed: 429 ...` | 4 |
245
+ | API 500 | `ForLoop API <method> <path> failed: 500 ...` | 7 |
246
+ | Non-JSON response | API error: unexpected response | 7 |
247
+
248
+ ### Process Signals
249
+
250
+ | Scenario | Behavior |
251
+ |---|---|
252
+ | Ctrl+C / SIGINT | `Interrupted. Exiting.` (exit code 130) |
253
+ | Piped output closed (EPIPE) | Silent exit 0 |
254
+
255
+ ### Config / Token File Corruption
256
+
257
+ | Scenario | Behavior |
258
+ |---|---|
259
+ | `~/.config/forloop/tokens.json` corrupted | Treated as no token; write error to stderr |
260
+ | Config file corrupted | Falls back to defaults with warning |