@clickminded/coauthor-cli 0.0.33 → 0.0.35
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 +1 -1
- package/dist/client.d.ts +6 -1
- package/dist/client.js +13 -2
- package/dist/commands.js +12 -6
- package/dist/index.d.ts +3 -1
- package/dist/index.js +7 -4
- package/package.json +1 -1
- package/skills/coauthor/references/images-and-social.md +1 -0
- package/skills/coauthor/references/troubleshooting.md +1 -0
- package/skills/cursor/coauthor-cli.mdc +2 -0
package/README.md
CHANGED
|
@@ -69,7 +69,7 @@ Images, social, and export:
|
|
|
69
69
|
|
|
70
70
|
```sh
|
|
71
71
|
coauthor image list <id> --json
|
|
72
|
-
coauthor image generate <id> --placeholder-id <id or placeholder_id> --json
|
|
72
|
+
coauthor image generate <id> --placeholder-id <id or placeholder_id> [--prompt "what it should show"] --json
|
|
73
73
|
coauthor image status <id> --json
|
|
74
74
|
coauthor repurpose generate <id> --format all --json # X thread and post, LinkedIn, Facebook, email newsletter
|
|
75
75
|
coauthor repurpose download <id> --out ./social # copy-ready files plus the article
|
package/dist/client.d.ts
CHANGED
|
@@ -36,12 +36,17 @@ export declare class AgentClient {
|
|
|
36
36
|
private readonly token;
|
|
37
37
|
private readonly fetchImpl;
|
|
38
38
|
private readonly options;
|
|
39
|
-
|
|
39
|
+
private readonly sent;
|
|
40
|
+
constructor(options: AgentClientOptions, sent?: {
|
|
41
|
+
count: number;
|
|
42
|
+
});
|
|
40
43
|
/** Same transport and timeouts, different credentials (used to verify a token before saving it). */
|
|
41
44
|
withCredentials(params: {
|
|
42
45
|
baseUrl?: string;
|
|
43
46
|
token: string;
|
|
44
47
|
}): AgentClient;
|
|
48
|
+
/** Requests and downloads started so far, across derived clients. */
|
|
49
|
+
get requestsSent(): number;
|
|
45
50
|
request(options: RequestOptions): Promise<JsonValue>;
|
|
46
51
|
/**
|
|
47
52
|
* Fetches a public file (a rendered MP4 or slide PNG on the CDN) as bytes.
|
package/dist/client.js
CHANGED
|
@@ -47,17 +47,27 @@ export class AgentClient {
|
|
|
47
47
|
token;
|
|
48
48
|
fetchImpl;
|
|
49
49
|
options;
|
|
50
|
-
|
|
50
|
+
// Shared with clients derived by withCredentials, so the CLI can tell a
|
|
51
|
+
// command rejected before anything was sent (a usage error) from one that
|
|
52
|
+
// failed while talking to CoAuthor.
|
|
53
|
+
sent;
|
|
54
|
+
constructor(options, sent = { count: 0 }) {
|
|
51
55
|
this.options = options;
|
|
56
|
+
this.sent = sent;
|
|
52
57
|
this.baseUrl = new URL('api/agent/v1/', normalizeBaseUrl(options.baseUrl));
|
|
53
58
|
this.token = options.token ?? '';
|
|
54
59
|
this.fetchImpl = options.fetchImpl ?? fetch;
|
|
55
60
|
}
|
|
56
61
|
/** Same transport and timeouts, different credentials (used to verify a token before saving it). */
|
|
57
62
|
withCredentials(params) {
|
|
58
|
-
return new AgentClient({ ...this.options, baseUrl: params.baseUrl ?? this.options.baseUrl, token: params.token });
|
|
63
|
+
return new AgentClient({ ...this.options, baseUrl: params.baseUrl ?? this.options.baseUrl, token: params.token }, this.sent);
|
|
64
|
+
}
|
|
65
|
+
/** Requests and downloads started so far, across derived clients. */
|
|
66
|
+
get requestsSent() {
|
|
67
|
+
return this.sent.count;
|
|
59
68
|
}
|
|
60
69
|
async request(options) {
|
|
70
|
+
this.sent.count += 1;
|
|
61
71
|
const method = options.method ?? 'GET';
|
|
62
72
|
const url = new URL(trimLeadingSlash(options.path), this.baseUrl);
|
|
63
73
|
const headers = new Headers({
|
|
@@ -104,6 +114,7 @@ export class AgentClient {
|
|
|
104
114
|
const target = new URL(url);
|
|
105
115
|
if (target.protocol !== 'https:' && target.protocol !== 'http:')
|
|
106
116
|
throw new Error(`Refusing to download a non-http URL: ${url}`);
|
|
117
|
+
this.sent.count += 1;
|
|
107
118
|
const timeoutMs = this.options.timeoutMs ?? requestTimeoutOverrideMs() ?? DEFAULT_DOWNLOAD_TIMEOUT_MS;
|
|
108
119
|
return withTimeout(timeoutMs, `download ${url}`, undefined, async (signal) => {
|
|
109
120
|
const response = await this.fetchImpl(target, { method: 'GET', signal });
|
package/dist/commands.js
CHANGED
|
@@ -779,6 +779,9 @@ async function runResourceCommand(resource, action, input, client) {
|
|
|
779
779
|
return liveOperationRequest(client, input, `${basePath}/${resolvedAction}`, exportRequestBody(resolvedAction, input));
|
|
780
780
|
}
|
|
781
781
|
if (resource === 'images' && resolvedAction === 'generate' && getBoolean(input.values, 'all')) {
|
|
782
|
+
if (getString(input.values, 'prompt') !== undefined) {
|
|
783
|
+
throw new Error('--prompt steers one image: use it with --placeholder-id <id>, not --all.');
|
|
784
|
+
}
|
|
782
785
|
return generateAllImages(client, projectId, getBoolean(input.values, 'wait'));
|
|
783
786
|
}
|
|
784
787
|
if (resource === 'images' && resolvedAction === 'metadata') {
|
|
@@ -804,11 +807,12 @@ async function runResourceCommand(resource, action, input, client) {
|
|
|
804
807
|
});
|
|
805
808
|
return { ok: true, data };
|
|
806
809
|
}
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
//
|
|
810
|
+
const imagePrompt = resource === 'images' && resolvedAction === 'generate';
|
|
811
|
+
if (getString(input.values, 'prompt') !== undefined && !imagePrompt) {
|
|
812
|
+
// Only image generate reads a free-form prompt (it becomes the image's
|
|
813
|
+
// scene); anywhere else it used to be silently dropped.
|
|
810
814
|
throw new Error(resource === 'images'
|
|
811
|
-
? `image ${resolvedAction} does not take --prompt.
|
|
815
|
+
? `image ${resolvedAction} does not take --prompt. To change an existing image, use --edit-prompt "...".`
|
|
812
816
|
: `${name} ${resolvedAction} does not take --prompt.`);
|
|
813
817
|
}
|
|
814
818
|
const body = withNamedOptions(parseJsonOption(input.values), input.values, [
|
|
@@ -822,6 +826,7 @@ async function runResourceCommand(resource, action, input, client) {
|
|
|
822
826
|
'grounding-mode',
|
|
823
827
|
'image-generation-model',
|
|
824
828
|
...(resource === 'threads' && resolvedAction === 'generate' ? ['writing-model'] : []),
|
|
829
|
+
...(imagePrompt ? ['prompt'] : []),
|
|
825
830
|
'edit-prompt',
|
|
826
831
|
]);
|
|
827
832
|
const path = resolvedAction === 'create' && resource !== 'threads' ? basePath : `${basePath}/${resolvedAction}`;
|
|
@@ -2594,10 +2599,11 @@ function commandHelp(command) {
|
|
|
2594
2599
|
'show: status and the proposed groups. apply: keep every group, or only --accept / all but --reject. discard: drop the revision (cancels it if still running).',
|
|
2595
2600
|
].join('\n'),
|
|
2596
2601
|
'image generate': [
|
|
2597
|
-
'Usage: coauthor image generate <project-id> --placeholder-id <id> [--grounding-mode <mode>] [--image-generation-model <id>] [--json]',
|
|
2602
|
+
'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--json]',
|
|
2598
2603
|
'',
|
|
2599
2604
|
'Pass the placeholder `id` (UUID) or its `placeholder_id` from coauthor image list. Draft generation creates placeholders.',
|
|
2600
|
-
'Images are drawn from the planned brief
|
|
2605
|
+
'Images are drawn from the planned brief. --prompt replaces the brief\'s scene (what the image shows) and is saved, so later regenerations keep it;',
|
|
2606
|
+
'the profile\'s visual style still applies. Comparison and technical-diagram images have no scene to replace: generate them, then use image edit --edit-prompt.',
|
|
2601
2607
|
'Generation is asynchronous: poll coauthor image status <project-id> --json until it is done.',
|
|
2602
2608
|
].join('\n'),
|
|
2603
2609
|
'image edit': [
|
package/dist/index.d.ts
CHANGED
|
@@ -5,7 +5,9 @@ export type CliIo = {
|
|
|
5
5
|
stderr: (text: string) => void;
|
|
6
6
|
};
|
|
7
7
|
export declare function main(argv?: string[], io?: CliIo): Promise<number>;
|
|
8
|
-
export declare function formatCliError(error: unknown, baseUrl: string, argv?: string[]
|
|
8
|
+
export declare function formatCliError(error: unknown, baseUrl: string, argv?: string[], context?: {
|
|
9
|
+
requestsSent?: number;
|
|
10
|
+
}): {
|
|
9
11
|
error: Error;
|
|
10
12
|
result?: JsonValue;
|
|
11
13
|
exitCode: number;
|
package/dist/index.js
CHANGED
|
@@ -12,6 +12,7 @@ const processIo = {
|
|
|
12
12
|
};
|
|
13
13
|
export async function main(argv = process.argv.slice(2), io = processIo) {
|
|
14
14
|
let resolvedBaseUrl = resolveBaseUrlFromArgv(argv);
|
|
15
|
+
let client;
|
|
15
16
|
try {
|
|
16
17
|
const parsed = parseCliArgs(argv);
|
|
17
18
|
if (parsed.globals.version || (parsed.command.length === 1 && parsed.command[0] === 'version')) {
|
|
@@ -27,7 +28,7 @@ export async function main(argv = process.argv.slice(2), io = processIo) {
|
|
|
27
28
|
tokenOverride: parsed.globals.token,
|
|
28
29
|
});
|
|
29
30
|
resolvedBaseUrl = runtimeConfig.baseUrl;
|
|
30
|
-
|
|
31
|
+
client = new AgentClient(runtimeConfig);
|
|
31
32
|
const result = await runCommand(parsed, {
|
|
32
33
|
client,
|
|
33
34
|
baseUrl: runtimeConfig.baseUrl,
|
|
@@ -44,14 +45,14 @@ export async function main(argv = process.argv.slice(2), io = processIo) {
|
|
|
44
45
|
}
|
|
45
46
|
catch (error) {
|
|
46
47
|
const wantsJson = argv.includes('--json');
|
|
47
|
-
const formatted = formatCliError(error, resolvedBaseUrl, argv);
|
|
48
|
+
const formatted = formatCliError(error, resolvedBaseUrl, argv, { requestsSent: client?.requestsSent ?? 0 });
|
|
48
49
|
io.stderr(wantsJson
|
|
49
50
|
? renderError(formatted.result ?? formatted.error, true)
|
|
50
51
|
: renderError(formatted.error, false));
|
|
51
52
|
return formatted.exitCode;
|
|
52
53
|
}
|
|
53
54
|
}
|
|
54
|
-
export function formatCliError(error, baseUrl, argv = []) {
|
|
55
|
+
export function formatCliError(error, baseUrl, argv = [], context = {}) {
|
|
55
56
|
if (error instanceof AgentHttpError) {
|
|
56
57
|
// Keep the server's error code and details (e.g. the current draft version
|
|
57
58
|
// on a 409) on every --json error so agents can recover without guessing.
|
|
@@ -110,7 +111,9 @@ export function formatCliError(error, baseUrl, argv = []) {
|
|
|
110
111
|
const normalized = error instanceof Error ? error : new Error(String(error));
|
|
111
112
|
return {
|
|
112
113
|
error: normalized,
|
|
113
|
-
|
|
114
|
+
// Anything rejected before the first request is the command's own fault
|
|
115
|
+
// (bad flag, missing argument, invalid value): a usage error.
|
|
116
|
+
result: { ok: false, error: normalized.message, code: context.requestsSent === 0 || isUsageMessage(normalized.message) ? 'usage_error' : 'cli_error', http_status: null },
|
|
114
117
|
exitCode: 1,
|
|
115
118
|
};
|
|
116
119
|
}
|
package/package.json
CHANGED
|
@@ -7,6 +7,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
|
|
|
7
7
|
1. `coauthor image list <id> --json` returns `data.placeholders`. Each has an `id` (UUID), a `purpose`, an `image_type`, and the planned brief.
|
|
8
8
|
2. Generate them all and wait: `coauthor image generate <id> --all --wait --json`. It skips images that are already done, and reports `done`, `failed`, and `still_running` (check again with `coauthor image status <id> --json`). Each image takes about 20 seconds.
|
|
9
9
|
3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID or the descriptive `placeholder_id`; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
|
|
10
|
+
- To steer what it shows, add `--prompt "..."`: it replaces the planned scene (describe the subject and composition; the writer profile's visual style is still applied, so don't name an art style). It is saved, so later regenerations keep it. Use it when the planned brief is off-topic or wrong, not for small tweaks to a finished image (that's `image edit`). Comparison and technical-diagram images refuse it (`structured_brief`); generate those, then edit.
|
|
10
11
|
4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
|
|
11
12
|
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
12
13
|
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
@@ -30,6 +30,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
30
30
|
| `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
|
|
31
31
|
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
32
32
|
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
33
|
+
| `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
|
|
33
34
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
34
35
|
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports and publishes, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
35
36
|
|
|
@@ -336,6 +336,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
|
|
|
336
336
|
1. `coauthor image list <id> --json` returns `data.placeholders`. Each has an `id` (UUID), a `purpose`, an `image_type`, and the planned brief.
|
|
337
337
|
2. Generate them all and wait: `coauthor image generate <id> --all --wait --json`. It skips images that are already done, and reports `done`, `failed`, and `still_running` (check again with `coauthor image status <id> --json`). Each image takes about 20 seconds.
|
|
338
338
|
3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID or the descriptive `placeholder_id`; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
|
|
339
|
+
- To steer what it shows, add `--prompt "..."`: it replaces the planned scene (describe the subject and composition; the writer profile's visual style is still applied, so don't name an art style). It is saved, so later regenerations keep it. Use it when the planned brief is off-topic or wrong, not for small tweaks to a finished image (that's `image edit`). Comparison and technical-diagram images refuse it (`structured_brief`); generate those, then edit.
|
|
339
340
|
4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
|
|
340
341
|
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
341
342
|
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
@@ -508,6 +509,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
508
509
|
| `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
|
|
509
510
|
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
510
511
|
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
512
|
+
| `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
|
|
511
513
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
512
514
|
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports and publishes, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
513
515
|
|