@clickminded/coauthor-cli 0.0.37 → 0.0.38

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
@@ -70,7 +70,8 @@ Images, social, and export:
70
70
  ```sh
71
71
  coauthor image list <id> --json
72
72
  coauthor image generate <id> --placeholder-id <id or placeholder_id> [--prompt "what it should show"] --json
73
- coauthor image status <id> --json
73
+ coauthor image status <id> [--artifact article|slideshow|video] --json
74
+ coauthor image replace <id> --placeholder-id <panel id> --file <path> --json # slideshow/video panels only
74
75
  coauthor repurpose generate <id> --format all --json # X thread and post, LinkedIn, Facebook, email newsletter
75
76
  coauthor repurpose download <id> --out ./social # copy-ready files plus the article
76
77
  coauthor share <id> --json # public read-only link
package/dist/commands.js CHANGED
@@ -722,7 +722,7 @@ const DRAFT_SAVE_SHAPE = 'Payload: {"document_id":"<from draft get>","expected_b
722
722
  // The actions each resource supports on the Agent API. Anything else used to
723
723
  // reach the server and come back as "Agent API route not found".
724
724
  const RESOURCE_ACTIONS = {
725
- images: ['list', 'status', 'show', 'generate', 'edit', 'metadata'],
725
+ images: ['list', 'status', 'show', 'generate', 'edit', 'metadata', 'replace'],
726
726
  threads: ['list', 'show', 'status', 'generate', 'save', 'create'],
727
727
  slideshows: ['list', 'show', 'status', 'generate', 'save'],
728
728
  publish: ['thread'],
@@ -743,6 +743,7 @@ async function runResourceCommand(resource, action, input, client) {
743
743
  if (!projectId)
744
744
  throw new Error(`Missing project id. Usage: coauthor ${name} ${resolvedAction} <project-id> [...]`);
745
745
  const basePath = `projects/${encodeURIComponent(projectId)}/${resource}`;
746
+ const artifactQuery = imageArtifactQuery(resource, resolvedAction, input);
746
747
  if (resolvedAction === 'list') {
747
748
  // These lists return everything for the project; the server has no
748
749
  // filters or pages for them, so don't pretend to send any.
@@ -751,12 +752,12 @@ async function runResourceCommand(resource, action, input, client) {
751
752
  throw new Error(`${name} list does not support --${flag}; it always returns every ${name === 'export' ? 'export' : 'item'} for the project.`);
752
753
  }
753
754
  }
754
- const data = await client.request({ path: basePath });
755
+ const data = await client.request({ path: `${basePath}${artifactQuery}` });
755
756
  return { ok: true, data };
756
757
  }
757
758
  if (resolvedAction === 'show' || resolvedAction === 'status') {
758
759
  if (resource === 'images' && resolvedAction === 'status') {
759
- const data = await client.request({ path: `${basePath}/status` });
760
+ const data = await client.request({ path: `${basePath}/status${artifactQuery}` });
760
761
  return { ok: true, data };
761
762
  }
762
763
  if (resource === 'threads' || resource === 'slideshows') {
@@ -785,7 +786,10 @@ async function runResourceCommand(resource, action, input, client) {
785
786
  if (getString(input.values, 'idempotency-key') !== undefined) {
786
787
  throw new Error('--idempotency-key names one image job: use it with --placeholder-id <id>, not --all (each image gets its own key in data.operations).');
787
788
  }
788
- return generateAllImages(client, projectId, getBoolean(input.values, 'wait'));
789
+ return generateAllImages(client, projectId, getBoolean(input.values, 'wait'), artifactQuery);
790
+ }
791
+ if (resource === 'images' && resolvedAction === 'replace') {
792
+ return replaceImage(client, input, basePath, projectId, resourceId);
789
793
  }
790
794
  if (resource === 'images' && resolvedAction === 'metadata') {
791
795
  if (!resourceId) {
@@ -866,6 +870,82 @@ async function imageOperationRequest(client, input, projectId, path, body, actio
866
870
  data,
867
871
  };
868
872
  }
873
+ const IMAGE_ARTIFACTS = ['article', 'slideshow', 'video'];
874
+ // `--artifact article|slideshow|video` narrows image list/status (and
875
+ // generate --all) to one artifact's placeholders. Without it, every image.
876
+ function imageArtifactQuery(resource, action, input) {
877
+ const artifact = getString(input.values, 'artifact');
878
+ if (artifact === undefined)
879
+ return '';
880
+ const supported = resource === 'images'
881
+ && (action === 'list' || action === 'status' || (action === 'generate' && getBoolean(input.values, 'all')));
882
+ if (!supported) {
883
+ throw new Error('--artifact works with image list, image status, and image generate --all.');
884
+ }
885
+ const value = artifact.trim().toLowerCase();
886
+ if (!IMAGE_ARTIFACTS.includes(value)) {
887
+ throw new Error(`--artifact must be article, slideshow, or video (got "${artifact}").`);
888
+ }
889
+ return `?artifact=${value}`;
890
+ }
891
+ const REPLACE_IMAGE_MAX_BYTES = 12 * 1024 * 1024;
892
+ const REPLACE_IMAGE_TYPES = {
893
+ png: 'image/png',
894
+ jpg: 'image/jpeg',
895
+ jpeg: 'image/jpeg',
896
+ webp: 'image/webp',
897
+ gif: 'image/gif',
898
+ avif: 'image/avif',
899
+ };
900
+ const REPLACE_USAGE = 'Usage: coauthor image replace <project-id> --placeholder-id <id> (--file <path> | --url <url>) [--json]';
901
+ // Replaces a slideshow or video panel's image with your own. The panel is
902
+ // then marked uploaded: image edit still works, image generate is refused.
903
+ async function replaceImage(client, input, basePath, projectId, positionalId) {
904
+ const placeholderRef = getString(input.values, 'placeholder-id') ?? positionalId;
905
+ if (!placeholderRef)
906
+ throw new Error(`Missing --placeholder-id. ${REPLACE_USAGE}`);
907
+ const file = getString(input.values, 'file');
908
+ const url = getString(input.values, 'url');
909
+ if (file !== undefined && url !== undefined)
910
+ throw new Error(`Pass --file or --url, not both. ${REPLACE_USAGE}`);
911
+ if (!file && !url)
912
+ throw new Error(`Pass the new image with --file <path> or --url <url>. ${REPLACE_USAGE}`);
913
+ let body;
914
+ if (url) {
915
+ if (!/^https?:\/\//i.test(url.trim()))
916
+ throw new Error('--url must be an http or https URL.');
917
+ body = { url: url.trim() };
918
+ }
919
+ else {
920
+ const path = resolve(file);
921
+ const extension = path.split('.').pop()?.toLowerCase() ?? '';
922
+ const contentType = REPLACE_IMAGE_TYPES[extension];
923
+ if (!contentType)
924
+ throw new Error('--file must be a PNG, JPEG, WebP, GIF, or AVIF image (.png, .jpg, .jpeg, .webp, .gif, .avif).');
925
+ let bytes;
926
+ try {
927
+ bytes = await readFile(path);
928
+ }
929
+ catch {
930
+ throw new Error(`Could not read --file ${file}.`);
931
+ }
932
+ if (bytes.length === 0)
933
+ throw new Error(`--file ${file} is empty.`);
934
+ if (bytes.length > REPLACE_IMAGE_MAX_BYTES)
935
+ throw new Error(`--file ${file} is too large (max 12 MB).`);
936
+ body = { data: bytes.toString('base64'), content_type: contentType, filename: basename(path) };
937
+ }
938
+ const data = await client.request({
939
+ method: 'POST',
940
+ path: `${basePath}/${encodeURIComponent(placeholderRef)}/replace`,
941
+ body,
942
+ });
943
+ return {
944
+ ok: true,
945
+ message: `Replaced the image for ${placeholderRef}. It is marked uploaded: coauthor image edit still works; image generate is refused for it. Check it with: coauthor image show ${projectId} ${placeholderRef} --json`,
946
+ data,
947
+ };
948
+ }
869
949
  // Publish and export run as recorded operations keyed by the Idempotency-Key.
870
950
  // Print the key so the caller can look the outcome up (`operation status`) or
871
951
  // replay the same request safely with --idempotency-key.
@@ -2175,8 +2255,8 @@ function imageStatusRows(data) {
2175
2255
  // Generates every planned image that isn't already done or generating, then
2176
2256
  // optionally waits (under the 10-minute agent shell limit) until none are
2177
2257
  // still generating.
2178
- async function generateAllImages(client, projectId, wait) {
2179
- const statusPath = `projects/${encodeURIComponent(projectId)}/images/status`;
2258
+ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
2259
+ const statusPath = `projects/${encodeURIComponent(projectId)}/images/status${artifactQuery}`;
2180
2260
  const before = imageStatusRows(await client.request({ path: statusPath }));
2181
2261
  const toGenerate = before.filter((row) => row.status !== 'done' && row.status !== 'generating');
2182
2262
  const started = [];
@@ -2427,7 +2507,7 @@ export function helpResult(command = []) {
2427
2507
  ' draft get supports --format json|markdown|html|text',
2428
2508
  ' workflow show|status|advance|run|rewind|approve|resume',
2429
2509
  ' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
2430
- ' image list|status|show|generate|edit|metadata',
2510
+ ' image list|status|show|generate|edit|metadata|replace',
2431
2511
  ' thread list|show|create|generate|save',
2432
2512
  ' slideshow show|save',
2433
2513
  ' publish thread (supports --idempotency-key)',
@@ -2597,11 +2677,13 @@ function commandHelp(command) {
2597
2677
  "Talk to CoAuthor about the project. The reply text is in data.text. Re-read the artifact afterwards: CoAuthor's summary can differ from what was saved.",
2598
2678
  ].join('\n'),
2599
2679
  image: [
2600
- 'Usage: coauthor image <list|status|show|generate|edit|metadata> <project-id> [...] [--json]',
2601
- ' coauthor image generate <project-id> --all [--wait] [--json] (every planned image; --wait until they finish)',
2680
+ 'Usage: coauthor image <list|status|show|generate|edit|metadata|replace> <project-id> [...] [--json]',
2681
+ ' coauthor image generate <project-id> --all [--artifact <kind>] [--wait] [--json] (every planned image; --wait until they finish)',
2602
2682
  '',
2603
2683
  'list: planned placeholders. generate/edit: --placeholder-id <id or placeholder_id> [--edit-prompt "..."]. status: generation progress.',
2684
+ 'list/status: --artifact article|slideshow|video shows one artifact\'s images (each carries artifact, slot and source).',
2604
2685
  'metadata <project-id> <placeholder id>: --alt-text, --description, --file-slug.',
2686
+ 'replace <project-id> --placeholder-id <id> (--file <path> | --url <url>): use your own image for a slideshow or video panel.',
2605
2687
  ].join('\n'),
2606
2688
  thread: [
2607
2689
  'Usage: coauthor thread <show|generate|save> <project-id> [--data <json|@file>] [--writing-model <id>] [--json]',
@@ -2669,6 +2751,14 @@ function commandHelp(command) {
2669
2751
  'Prints an operation key (data.idempotency_key in --json): coauthor operation status <key> reports the finished image url or the error.',
2670
2752
  '--idempotency-key <key> replays an earlier request with that key instead of queueing a second job. With --all, each image gets its own key (data.operations).',
2671
2753
  ].join('\n'),
2754
+ 'image replace': [
2755
+ REPLACE_USAGE,
2756
+ '',
2757
+ 'Replaces a slideshow or video panel\'s image with your own (PNG, JPEG, WebP, GIF or AVIF, up to 12 MB).',
2758
+ 'Find panels with coauthor image list <project-id> --artifact slideshow (or video); pass the placeholder id or placeholder_id.',
2759
+ 'The panel is then marked uploaded (source: "uploaded"): image edit still works, image generate is refused (uploaded_image),',
2760
+ 'and restyling panels skips it. Article and featured images cannot be replaced here.',
2761
+ ].join('\n'),
2672
2762
  'image edit': [
2673
2763
  'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--json]',
2674
2764
  '',
package/dist/parser.js CHANGED
@@ -77,6 +77,9 @@ const OPTIONS = {
77
77
  accept: { type: 'string' },
78
78
  reject: { type: 'string' },
79
79
  'idempotency-key': { type: 'string' },
80
+ file: { type: 'string' },
81
+ url: { type: 'string' },
82
+ artifact: { type: 'string' },
80
83
  };
81
84
  /** True when `--name` (or its short alias) consumes the next argv entry as its value. */
82
85
  export function optionTakesValue(flag) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.37",
3
+ "version": "0.0.38",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -14,6 +14,8 @@ Draft generation plans image placeholders, including a featured image (`is_featu
14
14
  - Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
15
15
  - Prices, dates, and text inside the image must match the article.
16
16
  5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --json`, then poll `image status` again. To drop an image entirely, remove its `imagePlaceholder` node with a direct draft edit (`references/editing-drafts.md`).
17
+ - Replace a slideshow or video panel with the user's own image: `coauthor image replace <id> --placeholder-id <id> --file <path>` (or `--url <url>`; PNG, JPEG, WebP, GIF, or AVIF, up to about 3 MB as a file, larger by URL). The panel is then marked `source: "uploaded"`: `image edit` still works, `image generate` is refused (`uploaded_image`). Article images can't be replaced from the CLI.
18
+ - `image list` and `image status` include slideshow and video panels; each row has `artifact` (`article`, `slideshow`, `video`) and `slot`. Filter with `--artifact article|slideshow|video` (also on `image generate --all`).
17
19
  6. Rewrite the SEO metadata for every generated image: `coauthor image metadata <id> <placeholder id UUID> --alt-text "..." --file-slug "..." --description "..." --json`. This is required, not polish: the stored alt text was written from the plan before the image existed and often describes things that aren't in the picture. Alt text must describe what is actually visible.
18
20
 
19
21
  Images cost credits each time they are generated or edited, so check the brief and placeholder purpose before regenerating.
@@ -52,6 +52,8 @@ A carousel of 1080x1350 slides (for LinkedIn or Instagram) with illustrated pane
52
52
  2. `coauthor repurpose status <id> --format slideshow --wait --json` waits until no panel is still generating. If some failed, retry them with `coauthor image generate` or in the web app.
53
53
  3. `coauthor repurpose download <id> --format slideshow [--variant <cta>] --out <dir>` renders the PNGs on the server and saves them as `slideshow/<cta>/slide-NN.png`, one folder per ending. `panels_not_ready` (409) means images are still generating or failed. Rendering again with no changes returns the same files.
54
54
 
55
+ Each slide's illustrated panel can be fixed one at a time, the same as article images (see `references/images-and-social.md`): `coauthor image list <id> --artifact slideshow --json` lists the panels with their `slot` (slide number, core or CTA ending), then `image generate --placeholder-id <id> [--prompt "..."]`, `image edit --placeholder-id <id> --edit-prompt "..."`, or `image replace --placeholder-id <id> --file <path>|--url <url>` to use the user's own image. Download again afterwards to get the new PNGs.
56
+
55
57
  The server draws the slides with the Inter font, so line breaks can differ slightly from the web app's own PNG download.
56
58
 
57
59
  ## Video
@@ -63,6 +65,8 @@ A short vertical video (1080x1920) of the article's key points, with illustrated
63
65
  3. `coauthor repurpose render <id> --format video [--variant <id>] --wait --json` renders the MP4. It takes about 3 minutes for a typical video and runs on a shared queue, so only one render per account at a time: `render_in_progress` (429) means wait for the current one. `panels_not_ready` (409) means the panel images aren't finished yet.
64
66
  4. `coauthor repurpose download <id> --format video --out <dir>` saves `video-<variant>.mp4`.
65
67
 
68
+ To fix one panel before rendering: `coauthor image list <id> --artifact video --json`, then `image generate`, `image edit`, or `image replace` on its `--placeholder-id`, and render again.
69
+
66
70
  ## Deliver
67
71
 
68
72
  `coauthor repurpose download <id> --out <dir>` writes:
@@ -31,6 +31,8 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
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
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 "..."`. |
34
+ | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
35
+ | `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
34
36
  | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
35
37
  | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
36
38
 
@@ -343,6 +343,8 @@ Draft generation plans image placeholders, including a featured image (`is_featu
343
343
  - Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
344
344
  - Prices, dates, and text inside the image must match the article.
345
345
  5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --json`, then poll `image status` again. To drop an image entirely, remove its `imagePlaceholder` node with a direct draft edit (`references/editing-drafts.md`).
346
+ - Replace a slideshow or video panel with the user's own image: `coauthor image replace <id> --placeholder-id <id> --file <path>` (or `--url <url>`; PNG, JPEG, WebP, GIF, or AVIF, up to about 3 MB as a file, larger by URL). The panel is then marked `source: "uploaded"`: `image edit` still works, `image generate` is refused (`uploaded_image`). Article images can't be replaced from the CLI.
347
+ - `image list` and `image status` include slideshow and video panels; each row has `artifact` (`article`, `slideshow`, `video`) and `slot`. Filter with `--artifact article|slideshow|video` (also on `image generate --all`).
346
348
  6. Rewrite the SEO metadata for every generated image: `coauthor image metadata <id> <placeholder id UUID> --alt-text "..." --file-slug "..." --description "..." --json`. This is required, not polish: the stored alt text was written from the plan before the image existed and often describes things that aren't in the picture. Alt text must describe what is actually visible.
347
349
 
348
350
  Images cost credits each time they are generated or edited, so check the brief and placeholder purpose before regenerating.
@@ -454,6 +456,8 @@ A carousel of 1080x1350 slides (for LinkedIn or Instagram) with illustrated pane
454
456
  2. `coauthor repurpose status <id> --format slideshow --wait --json` waits until no panel is still generating. If some failed, retry them with `coauthor image generate` or in the web app.
455
457
  3. `coauthor repurpose download <id> --format slideshow [--variant <cta>] --out <dir>` renders the PNGs on the server and saves them as `slideshow/<cta>/slide-NN.png`, one folder per ending. `panels_not_ready` (409) means images are still generating or failed. Rendering again with no changes returns the same files.
456
458
 
459
+ Each slide's illustrated panel can be fixed one at a time, the same as article images (see `references/images-and-social.md`): `coauthor image list <id> --artifact slideshow --json` lists the panels with their `slot` (slide number, core or CTA ending), then `image generate --placeholder-id <id> [--prompt "..."]`, `image edit --placeholder-id <id> --edit-prompt "..."`, or `image replace --placeholder-id <id> --file <path>|--url <url>` to use the user's own image. Download again afterwards to get the new PNGs.
460
+
457
461
  The server draws the slides with the Inter font, so line breaks can differ slightly from the web app's own PNG download.
458
462
 
459
463
  ### Video
@@ -465,6 +469,8 @@ A short vertical video (1080x1920) of the article's key points, with illustrated
465
469
  3. `coauthor repurpose render <id> --format video [--variant <id>] --wait --json` renders the MP4. It takes about 3 minutes for a typical video and runs on a shared queue, so only one render per account at a time: `render_in_progress` (429) means wait for the current one. `panels_not_ready` (409) means the panel images aren't finished yet.
466
470
  4. `coauthor repurpose download <id> --format video --out <dir>` saves `video-<variant>.mp4`.
467
471
 
472
+ To fix one panel before rendering: `coauthor image list <id> --artifact video --json`, then `image generate`, `image edit`, or `image replace` on its `--placeholder-id`, and render again.
473
+
468
474
  ### Deliver
469
475
 
470
476
  `coauthor repurpose download <id> --out <dir>` writes:
@@ -511,6 +517,8 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
511
517
  | `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
512
518
  | `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
513
519
  | `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 "..."`. |
520
+ | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
521
+ | `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
514
522
  | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
515
523
  | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
516
524