@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 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
- constructor(options: AgentClientOptions);
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
- constructor(options) {
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
- if (getString(input.values, 'prompt') !== undefined) {
808
- // No resource endpoint reads a free-form prompt (images are built from the
809
- // placeholder's planned brief), so --prompt used to be silently dropped.
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. Generate the image first, then direct changes with \`coauthor image edit <project-id> --placeholder-id <id> --edit-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; to steer one, generate it and then use coauthor image edit --edit-prompt.',
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
- const client = new AgentClient(runtimeConfig);
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
- result: { ok: false, error: normalized.message, code: isUsageMessage(normalized.message) ? 'usage_error' : 'cli_error', http_status: null },
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.33",
3
+ "version": "0.0.35",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -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