@clickminded/coauthor-cli 0.0.10 → 0.0.12
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/README.md +51 -103
- package/dist/client.d.ts +1 -0
- package/dist/client.js +2 -2
- package/dist/commands.d.ts +1 -1
- package/dist/commands.js +178 -68
- package/dist/config.d.ts +1 -1
- package/dist/config.js +1 -1
- package/dist/index.js +7 -5
- package/dist/parser.js +1 -1
- package/package.json +3 -3
- package/skills/agents/SKILL.md +5 -2
- package/skills/claude/SKILL.md +5 -2
- package/skills/codex/SKILL.md +5 -2
- package/skills/cursor/coauthor-cli.mdc +5 -2
package/README.md
CHANGED
|
@@ -1,16 +1,13 @@
|
|
|
1
1
|
# CoAuthor CLI
|
|
2
2
|
|
|
3
|
-
`@clickminded/coauthor-cli` installs the `coauthor` command for working with CoAuthor projects from a terminal or from AI coding agents such as Codex, Claude Code, and
|
|
3
|
+
`@clickminded/coauthor-cli` installs the `coauthor` command for working with CoAuthor projects from a terminal or from AI coding agents such as Codex, Claude Code, Cursor, and other local agents.
|
|
4
4
|
|
|
5
|
-
The CLI
|
|
5
|
+
The CLI connects to CoAuthor at `https://tools.clickminded.com/coauthor`. Your projects stay private and every project command requires browser/device login.
|
|
6
6
|
|
|
7
7
|
## Requirements
|
|
8
8
|
|
|
9
9
|
- Node.js 20 or newer.
|
|
10
|
-
- A CoAuthor account.
|
|
11
|
-
- The base URL for the CoAuthor workspace you want to use.
|
|
12
|
-
|
|
13
|
-
CoAuthor server setup, database migrations, and web app environment variables are maintainer/deployment concerns. They are not required for normal CLI users.
|
|
10
|
+
- A CoAuthor account with access to CoAuthor.
|
|
14
11
|
|
|
15
12
|
## Install
|
|
16
13
|
|
|
@@ -18,7 +15,6 @@ Install globally:
|
|
|
18
15
|
|
|
19
16
|
```sh
|
|
20
17
|
npm install -g @clickminded/coauthor-cli
|
|
21
|
-
coauthor auth status
|
|
22
18
|
```
|
|
23
19
|
|
|
24
20
|
Or run without a global install:
|
|
@@ -27,35 +23,23 @@ Or run without a global install:
|
|
|
27
23
|
npx @clickminded/coauthor-cli help
|
|
28
24
|
```
|
|
29
25
|
|
|
30
|
-
##
|
|
26
|
+
## Sign In
|
|
31
27
|
|
|
32
28
|
Start browser/device login:
|
|
33
29
|
|
|
34
30
|
```sh
|
|
35
|
-
coauthor auth login
|
|
31
|
+
coauthor auth login
|
|
36
32
|
```
|
|
37
33
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
```sh
|
|
41
|
-
coauthor auth login --base-url http://localhost:3000
|
|
42
|
-
```
|
|
34
|
+
The CLI opens a browser approval page. After approval, it stores a scoped local token for your signed-in CoAuthor account.
|
|
43
35
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
```sh
|
|
47
|
-
coauthor auth login --base-url <coauthor-app-url> --with-publish
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
The CLI opens a browser approval page. Approving there issues a scoped API token for the signed-in CoAuthor user.
|
|
51
|
-
|
|
52
|
-
Check the current token:
|
|
36
|
+
Check your login:
|
|
53
37
|
|
|
54
38
|
```sh
|
|
55
39
|
coauthor auth status --json
|
|
56
40
|
```
|
|
57
41
|
|
|
58
|
-
Log out and
|
|
42
|
+
Log out and revoke the local token:
|
|
59
43
|
|
|
60
44
|
```sh
|
|
61
45
|
coauthor auth logout
|
|
@@ -63,20 +47,6 @@ coauthor auth logout
|
|
|
63
47
|
|
|
64
48
|
Local credentials are stored at `~/.coauthor/config.json` with best-effort `0600` permissions. Do not print, paste, or commit this file.
|
|
65
49
|
|
|
66
|
-
Environment variables override the config file:
|
|
67
|
-
|
|
68
|
-
```sh
|
|
69
|
-
COAUTHOR_BASE_URL=<coauthor-app-url>
|
|
70
|
-
COAUTHOR_TOKEN=coauthor_xxx
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
Global options are:
|
|
74
|
-
|
|
75
|
-
- `--json` for machine-readable output.
|
|
76
|
-
- `--base-url <url>` to target a specific CoAuthor app.
|
|
77
|
-
- `--token <token>` for non-persistent token injection.
|
|
78
|
-
- `--data '<json>'` to send command-specific JSON request bodies.
|
|
79
|
-
|
|
80
50
|
## Agent Skills
|
|
81
51
|
|
|
82
52
|
Install agent instructions after installing the CLI:
|
|
@@ -101,34 +71,32 @@ Default install paths are:
|
|
|
101
71
|
- Cursor: `./.cursor/rules/coauthor-cli.mdc`
|
|
102
72
|
- Agents: `./.agents/skills/coauthor/SKILL.md`
|
|
103
73
|
|
|
104
|
-
Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install project-local Claude
|
|
74
|
+
Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install project-local Claude, Cursor, or Agents skills into a specific project.
|
|
105
75
|
|
|
106
|
-
Skill installs are recorded in `~/.config/coauthor/managed-skills.json`. Future
|
|
76
|
+
Skill installs are recorded in `~/.config/coauthor/managed-skills.json`. Future package updates automatically refresh recorded skill files when they still match the previously installed template. If you edit a skill file by hand, the auto-update leaves it alone until you run `coauthor skills install <target> --force`.
|
|
107
77
|
|
|
108
78
|
## Common Commands
|
|
109
79
|
|
|
110
|
-
|
|
80
|
+
Create and inspect projects:
|
|
111
81
|
|
|
112
82
|
```sh
|
|
113
|
-
coauthor project create --topic "
|
|
83
|
+
coauthor project create --title "Post title" --topic "Post brief" --audience "Target reader" --json
|
|
114
84
|
coauthor project list --json
|
|
115
85
|
coauthor project show <project-id> --json
|
|
116
86
|
coauthor workspace show <project-id> --json
|
|
117
87
|
```
|
|
118
88
|
|
|
119
|
-
|
|
89
|
+
Work with the project:
|
|
120
90
|
|
|
121
91
|
```sh
|
|
122
|
-
coauthor chat <project-id> --message "
|
|
92
|
+
coauthor chat <project-id> --message "Refine the angle for this post" --json
|
|
123
93
|
coauthor workflow status <project-id> --json
|
|
124
94
|
coauthor workflow run <project-id> --target draft --wait --json
|
|
125
95
|
coauthor workflow resume <project-id> --target draft --wait --json
|
|
126
|
-
coauthor workflow rewind <project-id> --stage outline --reason "..." --json
|
|
127
|
-
coauthor workflow approve <project-id> --stage research_plan --json
|
|
128
96
|
coauthor credits <project-id> --json
|
|
129
97
|
```
|
|
130
98
|
|
|
131
|
-
|
|
99
|
+
Read or generate artifacts:
|
|
132
100
|
|
|
133
101
|
```sh
|
|
134
102
|
coauthor contract show <project-id> --json
|
|
@@ -137,63 +105,61 @@ coauthor research-plan generate <project-id> --json
|
|
|
137
105
|
coauthor research run <project-id> --wait --json
|
|
138
106
|
coauthor draft generate <project-id> --wait --json
|
|
139
107
|
coauthor draft get <project-id> --format markdown --json
|
|
140
|
-
coauthor draft get <project-id> --format html --json
|
|
141
|
-
coauthor draft get <project-id> --format text --json
|
|
142
|
-
coauthor draft get <project-id> --format json --json
|
|
143
108
|
```
|
|
144
109
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
Images and threads:
|
|
110
|
+
Images and social content:
|
|
148
111
|
|
|
149
112
|
```sh
|
|
150
113
|
coauthor image list <project-id> --json
|
|
151
|
-
coauthor image generate <project-id> --prompt "
|
|
114
|
+
coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "Image direction" --json
|
|
152
115
|
coauthor thread generate <project-id> --json
|
|
153
|
-
coauthor thread save <project-id> --data '{"posts":[]}' --json
|
|
154
116
|
```
|
|
155
117
|
|
|
156
|
-
|
|
118
|
+
Use `--json` when another tool or agent needs to parse command output. Use `--wait` when starting longer-running work and you want the command to wait for completion.
|
|
119
|
+
|
|
120
|
+
## Draft Export
|
|
121
|
+
|
|
122
|
+
Export a finished draft in the format you need:
|
|
157
123
|
|
|
158
124
|
```sh
|
|
159
|
-
coauthor
|
|
160
|
-
coauthor
|
|
161
|
-
coauthor
|
|
162
|
-
coauthor
|
|
125
|
+
coauthor draft get <project-id> --format markdown --json
|
|
126
|
+
coauthor draft get <project-id> --format html --json
|
|
127
|
+
coauthor draft get <project-id> --format text --json
|
|
128
|
+
coauthor draft get <project-id> --format json --json
|
|
163
129
|
```
|
|
164
130
|
|
|
165
|
-
|
|
131
|
+
Markdown, HTML, and text exports resolve generated image URLs when images are available. Use `--format json` or omit `--format` for the raw editor document JSON.
|
|
166
132
|
|
|
167
|
-
##
|
|
133
|
+
## Live Actions
|
|
168
134
|
|
|
169
|
-
|
|
135
|
+
Publishing and external exports are real side effects. The default login grants project/workflow access only. To run live publish/export commands, sign in with publish permission:
|
|
170
136
|
|
|
171
137
|
```sh
|
|
172
|
-
coauthor
|
|
173
|
-
coauthor workflow run <project-id> --target outline --briefing-mode strict --max-brief-questions 2 --json
|
|
138
|
+
coauthor auth login --with-publish
|
|
174
139
|
```
|
|
175
140
|
|
|
176
|
-
|
|
141
|
+
Then run live actions only when you mean to publish or export:
|
|
177
142
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
-
|
|
143
|
+
```sh
|
|
144
|
+
coauthor publish thread <project-id> --yes --json
|
|
145
|
+
coauthor export blog <project-id> --yes --slug "post-slug" --json
|
|
146
|
+
coauthor export clickminded <project-id> --yes --json
|
|
147
|
+
coauthor operation status <operation-key> --json
|
|
148
|
+
```
|
|
181
149
|
|
|
182
|
-
|
|
150
|
+
Live actions require both publish scope and `--yes`.
|
|
183
151
|
|
|
184
152
|
## Agent Usage Rules
|
|
185
153
|
|
|
186
154
|
Agents should:
|
|
187
155
|
|
|
188
|
-
- Prefer `coauthor` over browser automation,
|
|
189
|
-
- Use `--json`
|
|
190
|
-
- Use `--wait` when starting
|
|
191
|
-
- Treat `status: "requires_key"` as a recoverable pause
|
|
192
|
-
- Treat `status: "
|
|
193
|
-
-
|
|
194
|
-
-
|
|
195
|
-
- Use `coauthor operation status <operation-key>` after uncertainty.
|
|
196
|
-
- Never print tokens, cookies, service-role keys, provider API keys, or authorization headers.
|
|
156
|
+
- Prefer `coauthor` commands over browser automation, hand-written HTTP requests, or direct database access.
|
|
157
|
+
- Use `--json` for machine-readable output.
|
|
158
|
+
- Use `--wait` when starting asynchronous work and the user expects the result.
|
|
159
|
+
- Treat `status: "requires_key"` or `paused_requires_key` as a recoverable pause. Ask the user to add the required provider key in CoAuthor AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
160
|
+
- Treat `status: "research_running_stale"` as a stale research run and inspect `coauthor research structured <project-id> --json` before retrying.
|
|
161
|
+
- Check operation status after timeouts, interruptions, network errors, or uncertain live-action results.
|
|
162
|
+
- Never print tokens, cookies, provider keys, service-role keys, or authorization headers.
|
|
197
163
|
|
|
198
164
|
## Security
|
|
199
165
|
|
|
@@ -203,34 +169,16 @@ Agents should:
|
|
|
203
169
|
- Tokens are stored locally at `~/.coauthor/config.json`.
|
|
204
170
|
- Run `coauthor auth logout` to revoke the current token and remove local credentials.
|
|
205
171
|
|
|
206
|
-
## Public API Stability
|
|
207
|
-
|
|
208
|
-
The CLI talks to `/api/agent/v1/*`. Treat this as a public beta API surface:
|
|
209
|
-
|
|
210
|
-
- Existing commands should keep stable JSON envelopes.
|
|
211
|
-
- New behavior should be additive when possible.
|
|
212
|
-
- Errors should stay structured and machine-readable with `--json`.
|
|
213
|
-
- Server-side auth, ownership checks, scopes, and rate limits remain mandatory.
|
|
214
|
-
|
|
215
172
|
## Troubleshooting
|
|
216
173
|
|
|
217
|
-
`No token configured` means the CLI has no
|
|
174
|
+
`No token configured` means the CLI has no saved CoAuthor credential. Run `coauthor auth login`.
|
|
218
175
|
|
|
219
|
-
`insufficient_scope` means the token does not include the required scope. For publish/export, log in again with
|
|
176
|
+
`insufficient_scope` means the token does not include the required scope. For publish/export, log in again with `coauthor auth login --with-publish`.
|
|
220
177
|
|
|
221
|
-
`authorization_pending` during login is normal while the browser approval page is waiting for
|
|
222
|
-
|
|
223
|
-
`requires_key` means included credits are exhausted and no usable provider key is configured for the requested capability. The task is paused when possible. Open AI settings in the web app, add the required key, then run `coauthor workflow resume <project-id> --wait --json`.
|
|
224
|
-
|
|
225
|
-
If `npx @clickminded/coauthor-cli help` fails while you are inside the CLI package source directory, run it from another directory or use:
|
|
226
|
-
|
|
227
|
-
```sh
|
|
228
|
-
npm exec --package=@clickminded/coauthor-cli@latest -- coauthor-cli help
|
|
229
|
-
```
|
|
178
|
+
`authorization_pending` during login is normal while the browser approval page is waiting for approval.
|
|
230
179
|
|
|
231
|
-
|
|
180
|
+
`requires_key` means included credits are exhausted and no usable provider key is configured for the requested capability. Open CoAuthor AI settings, add the required key, then run `coauthor workflow resume <project-id> --wait --json`.
|
|
232
181
|
|
|
233
|
-
|
|
182
|
+
`research_running_stale` means a research run is still marked running beyond the expected progress window. Inspect `coauthor research structured <project-id> --json`; if it only contains empty section shells, rewind research or report the stale run instead of repeatedly resuming.
|
|
234
183
|
|
|
235
|
-
- `
|
|
236
|
-
- `docs/skills.md`
|
|
184
|
+
Image generation requires an existing image placeholder. Run `coauthor image list <project-id> --json` after draft generation and pass the placeholder id to `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`.
|
package/dist/client.d.ts
CHANGED
package/dist/client.js
CHANGED
|
@@ -23,7 +23,7 @@ export class AgentClient {
|
|
|
23
23
|
token;
|
|
24
24
|
fetchImpl;
|
|
25
25
|
constructor(options) {
|
|
26
|
-
this.baseUrl = new URL('
|
|
26
|
+
this.baseUrl = new URL('api/agent/v1/', normalizeBaseUrl(options.baseUrl));
|
|
27
27
|
this.token = options.token ?? '';
|
|
28
28
|
this.fetchImpl = options.fetchImpl ?? fetch;
|
|
29
29
|
}
|
|
@@ -74,7 +74,7 @@ async function readResponseBody(response) {
|
|
|
74
74
|
return text;
|
|
75
75
|
}
|
|
76
76
|
}
|
|
77
|
-
function normalizeBaseUrl(baseUrl) {
|
|
77
|
+
export function normalizeBaseUrl(baseUrl) {
|
|
78
78
|
return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
|
|
79
79
|
}
|
|
80
80
|
function trimLeadingSlash(path) {
|
package/dist/commands.d.ts
CHANGED
|
@@ -9,4 +9,4 @@ export type CommandContext = {
|
|
|
9
9
|
token: string;
|
|
10
10
|
};
|
|
11
11
|
export declare function runCommand(input: ParsedCommand, context: CommandContext): Promise<CommandResult>;
|
|
12
|
-
export declare function helpResult(): CommandResult;
|
|
12
|
+
export declare function helpResult(command?: string[]): CommandResult;
|
package/dist/commands.js
CHANGED
|
@@ -5,7 +5,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
|
|
|
5
5
|
import { homedir } from 'node:os';
|
|
6
6
|
import { dirname, join, resolve } from 'node:path';
|
|
7
7
|
import { fileURLToPath } from 'node:url';
|
|
8
|
-
import { AgentHttpError } from './client.js';
|
|
8
|
+
import { AgentHttpError, normalizeBaseUrl } from './client.js';
|
|
9
9
|
import { clearConfig, loadConfig, saveConfig } from './config.js';
|
|
10
10
|
import { getBoolean, getString, parseJsonOption } from './parser.js';
|
|
11
11
|
export async function runCommand(input, context) {
|
|
@@ -27,17 +27,19 @@ export async function runCommand(input, context) {
|
|
|
27
27
|
if (scope === 'research-plan')
|
|
28
28
|
return runArtifactCommand('research-plan', action, input, context.client);
|
|
29
29
|
if (scope === 'research')
|
|
30
|
-
return runResearchCommand(action, input, context
|
|
30
|
+
return runResearchCommand(action, input, context);
|
|
31
31
|
if (scope === 'draft')
|
|
32
|
-
return runDraftCommand(action, input, context
|
|
32
|
+
return runDraftCommand(action, input, context);
|
|
33
33
|
if (scope === 'workflow')
|
|
34
|
-
return runWorkflowCommand(action, input, context
|
|
34
|
+
return runWorkflowCommand(action, input, context);
|
|
35
35
|
if (scope === 'credits')
|
|
36
36
|
return runCreditsCommand(input, context.client);
|
|
37
37
|
if (scope === 'image')
|
|
38
38
|
return runResourceCommand('images', action, input, context.client);
|
|
39
39
|
if (scope === 'thread')
|
|
40
40
|
return runResourceCommand('threads', action, input, context.client);
|
|
41
|
+
if (scope === 'slideshow')
|
|
42
|
+
return runResourceCommand('slideshows', action, input, context.client);
|
|
41
43
|
if (scope === 'publish')
|
|
42
44
|
return runResourceCommand('publish', action, input, context.client);
|
|
43
45
|
if (scope === 'export')
|
|
@@ -197,7 +199,8 @@ async function runChatCommand(action, input, client) {
|
|
|
197
199
|
data: enrichChatResult(data, projectId, stage),
|
|
198
200
|
};
|
|
199
201
|
}
|
|
200
|
-
async function runWorkflowCommand(action, input,
|
|
202
|
+
async function runWorkflowCommand(action, input, context) {
|
|
203
|
+
const { client } = context;
|
|
201
204
|
const projectId = requireProjectId(input);
|
|
202
205
|
const projectPath = `projects/${encodeURIComponent(projectId)}/workflow`;
|
|
203
206
|
if (action === 'show' || action === 'status') {
|
|
@@ -208,20 +211,20 @@ async function runWorkflowCommand(action, input, client) {
|
|
|
208
211
|
const target = normalizeWorkflowWaitTarget(getString(input.values, 'target') ?? getString(input.values, 'stage')) ?? 'draft';
|
|
209
212
|
if (target === 'research') {
|
|
210
213
|
const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/research/run`, body: {} });
|
|
211
|
-
return getBoolean(input.values, 'wait') ? waitForResearch(client, projectId, data) : { ok: true, data };
|
|
214
|
+
return getBoolean(input.values, 'wait') ? waitForResearch(client, projectId, data, context.baseUrl) : { ok: true, data };
|
|
212
215
|
}
|
|
213
216
|
const researchStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
|
|
214
217
|
if (extractNestedString(researchStatus, ['run', 'status']) === 'paused_requires_key') {
|
|
215
218
|
const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/research/run`, body: {} });
|
|
216
|
-
return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data) : { ok: true, data };
|
|
219
|
+
return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
|
|
217
220
|
}
|
|
218
221
|
const draftStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
219
222
|
if (getResponseString(draftStatus, 'phase') === 'paused_requires_key') {
|
|
220
223
|
const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: {} });
|
|
221
|
-
return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data) : { ok: true, data };
|
|
224
|
+
return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
|
|
222
225
|
}
|
|
223
226
|
const data = await client.request({ method: 'POST', path: `${projectPath}/run`, body: { target } });
|
|
224
|
-
return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data) : { ok: true, data };
|
|
227
|
+
return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
|
|
225
228
|
}
|
|
226
229
|
if (action === 'advance' || action === 'run' || action === 'rewind' || action === 'approve') {
|
|
227
230
|
const body = withNamedOptions(parseJsonOption(input.values), input.values, [
|
|
@@ -247,9 +250,9 @@ async function runWorkflowCommand(action, input, client) {
|
|
|
247
250
|
?? getString(input.values, 'stage')
|
|
248
251
|
?? getResponseString(data, 'target'));
|
|
249
252
|
if (target === 'research')
|
|
250
|
-
return waitForResearch(client, projectId, data);
|
|
253
|
+
return waitForResearch(client, projectId, data, context.baseUrl);
|
|
251
254
|
if (target === 'draft')
|
|
252
|
-
return waitForWorkflowDraft(client, projectId, data);
|
|
255
|
+
return waitForWorkflowDraft(client, projectId, data, context.baseUrl);
|
|
253
256
|
}
|
|
254
257
|
return { ok: true, data };
|
|
255
258
|
}
|
|
@@ -277,14 +280,15 @@ async function runArtifactCommand(artifact, action, input, client) {
|
|
|
277
280
|
}
|
|
278
281
|
throw new Error(`Usage: coauthor ${artifact} <show|generate|save|approve> <projectId>`);
|
|
279
282
|
}
|
|
280
|
-
async function runResearchCommand(action, input,
|
|
283
|
+
async function runResearchCommand(action, input, context) {
|
|
284
|
+
const { client } = context;
|
|
281
285
|
const projectId = requireProjectId(input);
|
|
282
286
|
const basePath = `projects/${encodeURIComponent(projectId)}/research`;
|
|
283
287
|
if (action === 'run') {
|
|
284
288
|
const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
|
|
285
289
|
const data = await client.request({ method: 'POST', path: `${basePath}/run`, body });
|
|
286
290
|
if (getBoolean(input.values, 'wait')) {
|
|
287
|
-
return waitForResearch(client, projectId, data);
|
|
291
|
+
return waitForResearch(client, projectId, data, context.baseUrl);
|
|
288
292
|
}
|
|
289
293
|
return { ok: true, data };
|
|
290
294
|
}
|
|
@@ -296,14 +300,15 @@ async function runResearchCommand(action, input, client) {
|
|
|
296
300
|
}
|
|
297
301
|
throw new Error('Usage: coauthor research <run|status|structured> <projectId>');
|
|
298
302
|
}
|
|
299
|
-
async function runDraftCommand(action, input,
|
|
303
|
+
async function runDraftCommand(action, input, context) {
|
|
304
|
+
const { client } = context;
|
|
300
305
|
const projectId = requireProjectId(input);
|
|
301
306
|
const basePath = `projects/${encodeURIComponent(projectId)}/draft`;
|
|
302
307
|
if (action === 'generate') {
|
|
303
308
|
const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
|
|
304
309
|
const data = await client.request({ method: 'POST', path: `${basePath}/generate`, body });
|
|
305
310
|
if (getBoolean(input.values, 'wait')) {
|
|
306
|
-
return waitForDraft(client, projectId, data);
|
|
311
|
+
return waitForDraft(client, projectId, data, context.baseUrl);
|
|
307
312
|
}
|
|
308
313
|
return { ok: true, data };
|
|
309
314
|
}
|
|
@@ -336,7 +341,7 @@ async function runResourceCommand(resource, action, input, client) {
|
|
|
336
341
|
const data = await client.request({ path: `${basePath}/status` });
|
|
337
342
|
return { ok: true, data };
|
|
338
343
|
}
|
|
339
|
-
if (resource === 'threads') {
|
|
344
|
+
if (resource === 'threads' || resource === 'slideshows') {
|
|
340
345
|
const data = await client.request({ path: resourceId ? `${basePath}/${encodeURIComponent(resourceId)}` : basePath });
|
|
341
346
|
return { ok: true, data };
|
|
342
347
|
}
|
|
@@ -631,11 +636,12 @@ function openBrowser(url) {
|
|
|
631
636
|
});
|
|
632
637
|
child.unref();
|
|
633
638
|
}
|
|
634
|
-
async function waitForResearch(client, projectId, initialData) {
|
|
635
|
-
const deadline = Date.now() + 20 * 60_000;
|
|
639
|
+
async function waitForResearch(client, projectId, initialData, baseUrl) {
|
|
640
|
+
const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
|
|
641
|
+
const pollMs = waitPollMs();
|
|
636
642
|
let latest = initialData;
|
|
637
643
|
while (Date.now() < deadline) {
|
|
638
|
-
await sleep(
|
|
644
|
+
await sleep(pollMs);
|
|
639
645
|
latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
|
|
640
646
|
const status = extractNestedString(latest, ['run', 'status']);
|
|
641
647
|
if (status === 'succeeded')
|
|
@@ -643,16 +649,20 @@ async function waitForResearch(client, projectId, initialData) {
|
|
|
643
649
|
if (status === 'failed')
|
|
644
650
|
throw new Error(extractNestedString(latest, ['run', 'error_message']) ?? 'Research failed');
|
|
645
651
|
if (status === 'paused_requires_key') {
|
|
646
|
-
return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest);
|
|
652
|
+
return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest, baseUrl);
|
|
647
653
|
}
|
|
654
|
+
const stale = researchRunningStaleResult(projectId, latest, null, initialData);
|
|
655
|
+
if (stale)
|
|
656
|
+
return stale;
|
|
648
657
|
}
|
|
649
|
-
return
|
|
658
|
+
return waitTimedOutResult(projectId, 'research', initialData, latest, null);
|
|
650
659
|
}
|
|
651
|
-
async function waitForDraft(client, projectId, initialData) {
|
|
652
|
-
const deadline = Date.now() + 20 * 60_000;
|
|
660
|
+
async function waitForDraft(client, projectId, initialData, baseUrl) {
|
|
661
|
+
const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
|
|
662
|
+
const pollMs = waitPollMs();
|
|
653
663
|
let latest = initialData;
|
|
654
664
|
while (Date.now() < deadline) {
|
|
655
|
-
await sleep(
|
|
665
|
+
await sleep(pollMs);
|
|
656
666
|
latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
657
667
|
const state = getResponseString(latest, 'project_state');
|
|
658
668
|
const phase = getResponseString(latest, 'phase');
|
|
@@ -660,23 +670,21 @@ async function waitForDraft(client, projectId, initialData) {
|
|
|
660
670
|
return { ok: true, message: 'Draft completed', data: latest };
|
|
661
671
|
}
|
|
662
672
|
if (phase === 'paused_requires_key')
|
|
663
|
-
return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest);
|
|
673
|
+
return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest, baseUrl);
|
|
664
674
|
if (phase === 'failed')
|
|
665
675
|
throw new Error(getResponseString(latest, 'message') ?? 'Draft generation failed');
|
|
666
676
|
}
|
|
667
|
-
return
|
|
677
|
+
return waitTimedOutResult(projectId, 'draft', initialData, null, latest);
|
|
668
678
|
}
|
|
669
|
-
async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
670
|
-
const deadline = Date.now() + 40 * 60_000;
|
|
679
|
+
async function waitForWorkflowDraft(client, projectId, initialData, baseUrl) {
|
|
680
|
+
const deadline = Date.now() + waitTimeoutMs(40 * 60_000);
|
|
681
|
+
const pollMs = waitPollMs();
|
|
671
682
|
let latestDraft = initialData;
|
|
672
683
|
let latestResearch = null;
|
|
673
684
|
let draftGenerate = null;
|
|
674
685
|
let attemptedDraftStart = false;
|
|
675
|
-
if (workflowIndicatesBackgroundResearch(initialData)) {
|
|
676
|
-
return researchRunningWorkflowResult(projectId, initialData, null, null);
|
|
677
|
-
}
|
|
678
686
|
while (Date.now() < deadline) {
|
|
679
|
-
await sleep(
|
|
687
|
+
await sleep(pollMs);
|
|
680
688
|
latestDraft = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
681
689
|
const draftState = getResponseString(latestDraft, 'project_state');
|
|
682
690
|
const draftPhase = getResponseString(latestDraft, 'phase');
|
|
@@ -699,7 +707,7 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
|
699
707
|
workflow: initialData,
|
|
700
708
|
research_status: latestResearch,
|
|
701
709
|
draft_status: latestDraft,
|
|
702
|
-
});
|
|
710
|
+
}, baseUrl);
|
|
703
711
|
}
|
|
704
712
|
latestResearch = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
|
|
705
713
|
const researchStatus = extractNestedString(latestResearch, ['run', 'status']);
|
|
@@ -711,8 +719,11 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
|
711
719
|
workflow: initialData,
|
|
712
720
|
research_status: latestResearch,
|
|
713
721
|
draft_status: latestDraft,
|
|
714
|
-
});
|
|
722
|
+
}, baseUrl);
|
|
715
723
|
}
|
|
724
|
+
const stale = researchRunningStaleResult(projectId, latestResearch, latestDraft, initialData);
|
|
725
|
+
if (stale)
|
|
726
|
+
return stale;
|
|
716
727
|
if (!attemptedDraftStart
|
|
717
728
|
&& (researchStatus === 'succeeded' || isResearchReadyForDraft(draftState))
|
|
718
729
|
&& draftPhase !== 'queued'
|
|
@@ -731,13 +742,73 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
|
731
742
|
}
|
|
732
743
|
}
|
|
733
744
|
}
|
|
745
|
+
return waitTimedOutResult(projectId, 'workflow draft target', initialData, latestResearch, latestDraft);
|
|
746
|
+
}
|
|
747
|
+
function waitPollMs() {
|
|
748
|
+
const raw = Number(process.env.COAUTHOR_CLI_WAIT_POLL_MS);
|
|
749
|
+
return Number.isFinite(raw) && raw >= 0 ? raw : 3000;
|
|
750
|
+
}
|
|
751
|
+
function waitTimeoutMs(defaultMs) {
|
|
752
|
+
const raw = Number(process.env.COAUTHOR_CLI_WAIT_TIMEOUT_MS);
|
|
753
|
+
return Number.isFinite(raw) && raw > 0 ? raw : defaultMs;
|
|
754
|
+
}
|
|
755
|
+
function researchStaleMs() {
|
|
756
|
+
const raw = Number(process.env.COAUTHOR_CLI_RESEARCH_STALE_MS);
|
|
757
|
+
return Number.isFinite(raw) && raw > 0 ? raw : 10 * 60_000;
|
|
758
|
+
}
|
|
759
|
+
function researchRunAgeMs(data) {
|
|
760
|
+
const timestamp = extractNestedString(data, ['run', 'updated_at'])
|
|
761
|
+
?? extractNestedString(data, ['run', 'created_at']);
|
|
762
|
+
if (!timestamp)
|
|
763
|
+
return null;
|
|
764
|
+
const time = Date.parse(timestamp);
|
|
765
|
+
if (!Number.isFinite(time))
|
|
766
|
+
return null;
|
|
767
|
+
return Date.now() - time;
|
|
768
|
+
}
|
|
769
|
+
function isResearchRunningStale(data) {
|
|
770
|
+
if (extractNestedString(data, ['run', 'status']) !== 'running')
|
|
771
|
+
return false;
|
|
772
|
+
if (getResponseString(data, 'project_state') !== 'research_running')
|
|
773
|
+
return false;
|
|
774
|
+
const ageMs = researchRunAgeMs(data);
|
|
775
|
+
return typeof ageMs === 'number' && ageMs >= researchStaleMs();
|
|
776
|
+
}
|
|
777
|
+
function researchRunningStaleResult(projectId, researchStatus, draftStatus, workflow) {
|
|
778
|
+
if (!isResearchRunningStale(researchStatus))
|
|
779
|
+
return null;
|
|
734
780
|
return {
|
|
735
|
-
ok:
|
|
736
|
-
|
|
781
|
+
ok: false,
|
|
782
|
+
status: 'research_running_stale',
|
|
783
|
+
exitCode: 2,
|
|
784
|
+
message: 'Research is still marked running and has not reported a terminal state within the expected window.',
|
|
737
785
|
data: {
|
|
738
|
-
workflow
|
|
739
|
-
research_status:
|
|
740
|
-
draft_status:
|
|
786
|
+
workflow,
|
|
787
|
+
research_status: enrichResearchStatus(researchStatus),
|
|
788
|
+
draft_status: draftStatus,
|
|
789
|
+
next_commands: [
|
|
790
|
+
`coauthor research status ${projectId} --json`,
|
|
791
|
+
`coauthor research structured ${projectId} --json`,
|
|
792
|
+
`coauthor workflow rewind ${projectId} --target research --json`,
|
|
793
|
+
],
|
|
794
|
+
},
|
|
795
|
+
};
|
|
796
|
+
}
|
|
797
|
+
function waitTimedOutResult(projectId, target, workflow, researchStatus, draftStatus) {
|
|
798
|
+
return {
|
|
799
|
+
ok: false,
|
|
800
|
+
status: 'timed_out',
|
|
801
|
+
exitCode: 2,
|
|
802
|
+
message: `Timed out waiting for ${target}; check status before retrying.`,
|
|
803
|
+
data: {
|
|
804
|
+
workflow,
|
|
805
|
+
research_status: researchStatus,
|
|
806
|
+
draft_status: draftStatus,
|
|
807
|
+
next_commands: [
|
|
808
|
+
`coauthor research status ${projectId} --json`,
|
|
809
|
+
`coauthor draft status ${projectId} --json`,
|
|
810
|
+
`coauthor workflow resume ${projectId} --target draft --wait --json`,
|
|
811
|
+
],
|
|
741
812
|
},
|
|
742
813
|
};
|
|
743
814
|
}
|
|
@@ -790,7 +861,23 @@ function enrichResearchStatus(data) {
|
|
|
790
861
|
return data;
|
|
791
862
|
const runStatus = extractNestedString(data, ['run', 'status']);
|
|
792
863
|
const projectState = getResponseString(data, 'project_state');
|
|
793
|
-
if (runStatus !== 'running'
|
|
864
|
+
if (runStatus !== 'running')
|
|
865
|
+
return data;
|
|
866
|
+
if (isResearchRunningStale(data)) {
|
|
867
|
+
return {
|
|
868
|
+
...data,
|
|
869
|
+
diagnostic: {
|
|
870
|
+
code: 'research_running_stale',
|
|
871
|
+
message: 'Research is still marked running and has not reported a terminal state within the expected window. Inspect structured output before deciding whether to rewind.',
|
|
872
|
+
next_commands: [
|
|
873
|
+
'coauthor research status <project-id> --json',
|
|
874
|
+
'coauthor research structured <project-id> --json',
|
|
875
|
+
'coauthor workflow rewind <project-id> --target research --json',
|
|
876
|
+
],
|
|
877
|
+
},
|
|
878
|
+
};
|
|
879
|
+
}
|
|
880
|
+
if (projectState === 'research_running')
|
|
794
881
|
return data;
|
|
795
882
|
if (projectState === 'research_complete') {
|
|
796
883
|
return {
|
|
@@ -819,37 +906,15 @@ function enrichResearchStatus(data) {
|
|
|
819
906
|
},
|
|
820
907
|
};
|
|
821
908
|
}
|
|
822
|
-
function
|
|
823
|
-
if (!data || typeof data !== 'object' || Array.isArray(data))
|
|
824
|
-
return false;
|
|
825
|
-
return getResponseString(data, 'project_state') === 'research_running'
|
|
826
|
-
|| getResponseString(data, 'status') === 'research_running';
|
|
827
|
-
}
|
|
828
|
-
function researchRunningWorkflowResult(projectId, workflow, researchStatus, draftStatus) {
|
|
829
|
-
return {
|
|
830
|
-
ok: true,
|
|
831
|
-
status: 'research_running',
|
|
832
|
-
message: 'Research is running in the background. Draft generation has not started yet.',
|
|
833
|
-
data: {
|
|
834
|
-
workflow,
|
|
835
|
-
research_status: researchStatus,
|
|
836
|
-
draft_status: draftStatus,
|
|
837
|
-
next_commands: [
|
|
838
|
-
`coauthor research status ${projectId} --json`,
|
|
839
|
-
`coauthor workflow resume ${projectId} --target draft --wait --json`,
|
|
840
|
-
`coauthor workflow rewind ${projectId} --target research --json`,
|
|
841
|
-
],
|
|
842
|
-
},
|
|
843
|
-
};
|
|
844
|
-
}
|
|
845
|
-
function requiresKeyPauseResult(projectId, target, message, data) {
|
|
909
|
+
function requiresKeyPauseResult(projectId, target, message, data, baseUrl) {
|
|
846
910
|
const resumeCommand = `coauthor workflow resume ${projectId} --target ${target} --wait --json`;
|
|
911
|
+
const settingsUrl = new URL('settings/ai', normalizeBaseUrl(baseUrl)).toString();
|
|
847
912
|
return {
|
|
848
913
|
ok: false,
|
|
849
914
|
status: 'requires_key',
|
|
850
915
|
exitCode: 2,
|
|
851
|
-
message: `${message}\nOpen AI settings:
|
|
852
|
-
settings_url:
|
|
916
|
+
message: `${message}\nOpen AI settings: ${settingsUrl}\nResume: ${resumeCommand}`,
|
|
917
|
+
settings_url: settingsUrl,
|
|
853
918
|
resume_command: resumeCommand,
|
|
854
919
|
data,
|
|
855
920
|
};
|
|
@@ -903,16 +968,19 @@ function resourceCommandName(resource) {
|
|
|
903
968
|
return 'image';
|
|
904
969
|
if (resource === 'threads')
|
|
905
970
|
return 'thread';
|
|
971
|
+
if (resource === 'slideshows')
|
|
972
|
+
return 'slideshow';
|
|
906
973
|
if (resource === 'exports')
|
|
907
974
|
return 'export';
|
|
908
975
|
if (resource === 'operations')
|
|
909
976
|
return 'operation';
|
|
910
977
|
return resource;
|
|
911
978
|
}
|
|
912
|
-
export function helpResult() {
|
|
979
|
+
export function helpResult(command = []) {
|
|
980
|
+
const scoped = commandHelp(command);
|
|
913
981
|
return {
|
|
914
982
|
ok: true,
|
|
915
|
-
message: [
|
|
983
|
+
message: scoped ?? [
|
|
916
984
|
'Usage: coauthor <command> [options]',
|
|
917
985
|
'',
|
|
918
986
|
'Commands:',
|
|
@@ -930,6 +998,7 @@ export function helpResult() {
|
|
|
930
998
|
' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
|
|
931
999
|
' image list|status|show|generate|edit',
|
|
932
1000
|
' thread list|show|create|generate|save',
|
|
1001
|
+
' slideshow show|save',
|
|
933
1002
|
' publish thread',
|
|
934
1003
|
' export blog|clickminded',
|
|
935
1004
|
' operation list|show|status',
|
|
@@ -939,3 +1008,44 @@ export function helpResult() {
|
|
|
939
1008
|
].join('\n'),
|
|
940
1009
|
};
|
|
941
1010
|
}
|
|
1011
|
+
function commandHelp(command) {
|
|
1012
|
+
const key = command.join(' ');
|
|
1013
|
+
const help = {
|
|
1014
|
+
'project create': [
|
|
1015
|
+
'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--json]',
|
|
1016
|
+
'',
|
|
1017
|
+
'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
|
|
1018
|
+
].join('\n'),
|
|
1019
|
+
'workflow run': [
|
|
1020
|
+
'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--wait] [--briefing-mode auto|strict|off] [--json]',
|
|
1021
|
+
'',
|
|
1022
|
+
'--wait blocks until the requested target completes, pauses for a key, fails, reports stale research, or times out.',
|
|
1023
|
+
].join('\n'),
|
|
1024
|
+
'workflow resume': [
|
|
1025
|
+
'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--wait] [--json]',
|
|
1026
|
+
'',
|
|
1027
|
+
'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
|
|
1028
|
+
].join('\n'),
|
|
1029
|
+
'draft generate': [
|
|
1030
|
+
'Usage: coauthor draft generate <project-id> [--wait] [--json]',
|
|
1031
|
+
'',
|
|
1032
|
+
'Requires project_state "research_structured". If research is still running or structuring, inspect the returned status and next commands.',
|
|
1033
|
+
].join('\n'),
|
|
1034
|
+
'draft get': [
|
|
1035
|
+
'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--json]',
|
|
1036
|
+
'',
|
|
1037
|
+
'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
|
|
1038
|
+
].join('\n'),
|
|
1039
|
+
'draft save': [
|
|
1040
|
+
'Usage: coauthor draft save <project-id> --data \'<json>\' [--json]',
|
|
1041
|
+
'',
|
|
1042
|
+
'Saves a draft document payload through the agent API.',
|
|
1043
|
+
].join('\n'),
|
|
1044
|
+
'image generate': [
|
|
1045
|
+
'Usage: coauthor image generate <project-id> --placeholder-id <placeholder-id> [--prompt "..."] [--json]',
|
|
1046
|
+
'',
|
|
1047
|
+
'Image generation requires an image placeholder from coauthor image list. Draft generation creates placeholders.',
|
|
1048
|
+
].join('\n'),
|
|
1049
|
+
};
|
|
1050
|
+
return help[key] ?? null;
|
|
1051
|
+
}
|
package/dist/config.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
export declare const DEFAULT_BASE_URL = "
|
|
2
|
+
export declare const DEFAULT_BASE_URL = "https://tools.clickminded.com/coauthor";
|
|
3
3
|
declare const configSchema: z.ZodObject<{
|
|
4
4
|
baseUrl: z.ZodOptional<z.ZodString>;
|
|
5
5
|
token: z.ZodOptional<z.ZodString>;
|
package/dist/config.js
CHANGED
|
@@ -2,7 +2,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
|
|
|
2
2
|
import { homedir } from 'node:os';
|
|
3
3
|
import { dirname, join } from 'node:path';
|
|
4
4
|
import { z } from 'zod';
|
|
5
|
-
export const DEFAULT_BASE_URL = '
|
|
5
|
+
export const DEFAULT_BASE_URL = 'https://tools.clickminded.com/coauthor';
|
|
6
6
|
const configSchema = z.object({
|
|
7
7
|
baseUrl: z.string().url().optional(),
|
|
8
8
|
token: z.string().min(1).optional(),
|
package/dist/index.js
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { realpathSync } from 'node:fs';
|
|
3
3
|
import { fileURLToPath } from 'node:url';
|
|
4
|
-
import { AgentHttpError, AgentClient } from './client.js';
|
|
5
|
-
import { resolveRuntimeConfig } from './config.js';
|
|
4
|
+
import { AgentHttpError, AgentClient, normalizeBaseUrl } from './client.js';
|
|
5
|
+
import { DEFAULT_BASE_URL, resolveRuntimeConfig } from './config.js';
|
|
6
6
|
import { helpResult, runCommand } from './commands.js';
|
|
7
7
|
import { renderError, renderResult } from './output.js';
|
|
8
8
|
import { parseCliArgs } from './parser.js';
|
|
@@ -11,7 +11,7 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
11
11
|
try {
|
|
12
12
|
const parsed = parseCliArgs(argv);
|
|
13
13
|
if (parsed.globals.help) {
|
|
14
|
-
process.stdout.write(renderResult(helpResult(), parsed.globals.json));
|
|
14
|
+
process.stdout.write(renderResult(helpResult(parsed.command), parsed.globals.json));
|
|
15
15
|
return 0;
|
|
16
16
|
}
|
|
17
17
|
const runtimeConfig = await resolveRuntimeConfig({
|
|
@@ -146,7 +146,9 @@ function formatRequiresKeyResult(body, baseUrl) {
|
|
|
146
146
|
const details = envelopeError.details && typeof envelopeError.details === 'object' && !Array.isArray(envelopeError.details)
|
|
147
147
|
? envelopeError.details
|
|
148
148
|
: {};
|
|
149
|
-
const settingsUrl = typeof details.settings_url === 'string'
|
|
149
|
+
const settingsUrl = typeof details.settings_url === 'string'
|
|
150
|
+
? details.settings_url
|
|
151
|
+
: new URL('settings/ai', normalizeBaseUrl(baseUrl)).toString();
|
|
150
152
|
const resumeCommand = typeof details.resume_command === 'string' ? details.resume_command : undefined;
|
|
151
153
|
return {
|
|
152
154
|
ok: false,
|
|
@@ -181,7 +183,7 @@ function extractEnvelopeError(body) {
|
|
|
181
183
|
function resolveBaseUrlFromArgv(argv) {
|
|
182
184
|
const index = argv.indexOf('--base-url');
|
|
183
185
|
const value = index >= 0 ? argv[index + 1] : undefined;
|
|
184
|
-
return value || process.env.COAUTHOR_BASE_URL ||
|
|
186
|
+
return value || process.env.COAUTHOR_BASE_URL || DEFAULT_BASE_URL;
|
|
185
187
|
}
|
|
186
188
|
function isCliEntrypoint() {
|
|
187
189
|
const argvPath = process.argv[1];
|
package/dist/parser.js
CHANGED
|
@@ -108,7 +108,7 @@ function commandLength(positionals) {
|
|
|
108
108
|
return second ? 2 : 1;
|
|
109
109
|
if (first === 'credits')
|
|
110
110
|
return 1;
|
|
111
|
-
if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'publish', 'export', 'operation'].includes(first ?? ''))
|
|
111
|
+
if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'slideshow', 'publish', 'export', 'operation'].includes(first ?? ''))
|
|
112
112
|
return second ? 2 : 1;
|
|
113
113
|
return 1;
|
|
114
114
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clickminded/coauthor-cli",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.12",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"bin": {
|
|
6
6
|
"coauthor": "dist/index.js",
|
|
@@ -8,8 +8,8 @@
|
|
|
8
8
|
},
|
|
9
9
|
"repository": {
|
|
10
10
|
"type": "git",
|
|
11
|
-
"url": "git+https://github.com/
|
|
12
|
-
"directory": "packages/cli"
|
|
11
|
+
"url": "git+https://github.com/ClickMinded/newsletter-generator.git",
|
|
12
|
+
"directory": "coauthor/packages/cli"
|
|
13
13
|
},
|
|
14
14
|
"exports": {
|
|
15
15
|
".": {
|
package/skills/agents/SKILL.md
CHANGED
|
@@ -9,15 +9,18 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
9
9
|
|
|
10
10
|
- Prefer `coauthor` CLI commands for CoAuthor project and workflow work.
|
|
11
11
|
- Do not drive browser routes, hand-written `curl`, or direct database edits when a CLI command covers the task.
|
|
12
|
-
- Use the
|
|
13
|
-
- For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000
|
|
12
|
+
- Use the built-in production base URL (`https://tools.clickminded.com/coauthor`) by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
|
|
13
|
+
- For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000/coauthor` or `COAUTHOR_BASE_URL=http://localhost:3000/coauthor` for mounted dev, or `--base-url http://localhost:3000` for a root-mounted app.
|
|
14
14
|
- Use `--json` for machine-readable output and parse fields from that output.
|
|
15
15
|
- Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
|
|
16
16
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
17
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
18
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
19
20
|
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
20
21
|
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
22
|
+
- `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
|
|
23
|
+
- For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
|
|
21
24
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
22
25
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
23
26
|
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
package/skills/claude/SKILL.md
CHANGED
|
@@ -9,15 +9,18 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
9
9
|
|
|
10
10
|
- Prefer `coauthor` CLI commands for CoAuthor project and workflow work.
|
|
11
11
|
- Do not drive browser routes, hand-written `curl`, or direct database edits when a CLI command covers the task.
|
|
12
|
-
- Use the
|
|
13
|
-
- For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000
|
|
12
|
+
- Use the built-in production base URL (`https://tools.clickminded.com/coauthor`) by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
|
|
13
|
+
- For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000/coauthor` or `COAUTHOR_BASE_URL=http://localhost:3000/coauthor` for mounted dev, or `--base-url http://localhost:3000` for a root-mounted app.
|
|
14
14
|
- Use `--json` for machine-readable output and parse fields from that output.
|
|
15
15
|
- Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
|
|
16
16
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
17
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
18
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
19
20
|
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
20
21
|
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
22
|
+
- `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
|
|
23
|
+
- For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
|
|
21
24
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
22
25
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
23
26
|
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
package/skills/codex/SKILL.md
CHANGED
|
@@ -9,15 +9,18 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
9
9
|
|
|
10
10
|
- Prefer `coauthor` CLI commands for CoAuthor project and workflow work.
|
|
11
11
|
- Do not drive browser routes, hand-written `curl`, or direct database edits when a CLI command covers the task.
|
|
12
|
-
- Use the
|
|
13
|
-
- For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000
|
|
12
|
+
- Use the built-in production base URL (`https://tools.clickminded.com/coauthor`) by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
|
|
13
|
+
- For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000/coauthor` or `COAUTHOR_BASE_URL=http://localhost:3000/coauthor` for mounted dev, or `--base-url http://localhost:3000` for a root-mounted app.
|
|
14
14
|
- Use `--json` for machine-readable output and parse fields from that output.
|
|
15
15
|
- Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
|
|
16
16
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
17
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
18
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
19
20
|
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
20
21
|
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
22
|
+
- `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
|
|
23
|
+
- For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
|
|
21
24
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
22
25
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
23
26
|
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
|
@@ -6,15 +6,18 @@ alwaysApply: true
|
|
|
6
6
|
# CoAuthor CLI
|
|
7
7
|
|
|
8
8
|
- Prefer the `coauthor` CLI for CoAuthor project/workflow operations instead of browser routes, hand-written `curl`, or direct database access.
|
|
9
|
-
- Use the
|
|
10
|
-
- For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000
|
|
9
|
+
- Use the built-in production base URL (`https://tools.clickminded.com/coauthor`) by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
|
|
10
|
+
- For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000/coauthor` or `COAUTHOR_BASE_URL=http://localhost:3000/coauthor` for mounted dev, or `--base-url http://localhost:3000` for a root-mounted app.
|
|
11
11
|
- Use `--json` for agent-readable command output.
|
|
12
12
|
- Use `--wait` when starting asynchronous work and the user expects a completed result.
|
|
13
13
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` for a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
14
14
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
15
15
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
16
|
+
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
16
17
|
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
17
18
|
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
19
|
+
- `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
|
|
20
|
+
- For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
|
|
18
21
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
19
22
|
- After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
|
|
20
23
|
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|