@clickminded/coauthor-cli 0.0.38 → 0.0.39

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
@@ -75,7 +75,10 @@ coauthor image replace <id> --placeholder-id <panel id> --file <path> --json #
75
75
  coauthor repurpose generate <id> --format all --json # X thread and post, LinkedIn, Facebook, email newsletter
76
76
  coauthor repurpose download <id> --out ./social # copy-ready files plus the article
77
77
  coauthor share <id> --json # public read-only link
78
- coauthor export wordpress <id> --yes --slug <slug> --json # creates a WordPress draft post
78
+ coauthor post-details show <id> --json # SEO title, meta description, slug, excerpt
79
+ coauthor post-details set <id> --seo-title "..." --json # exports use these as defaults
80
+ coauthor draft get <id> --format markdown --frontmatter --json # markdown with YAML frontmatter
81
+ coauthor export wordpress <id> --yes --json # creates a WordPress draft post (--slug to override)
79
82
  coauthor credits <id> --json
80
83
  coauthor integrations list --json # WordPress sites and X accounts
81
84
  ```
@@ -89,7 +92,7 @@ Publishing an X thread and exporting to WordPress are real side effects. They ne
89
92
  ```sh
90
93
  coauthor auth login --with-publish
91
94
  coauthor publish thread <id> --yes --json
92
- coauthor export wordpress <id> --yes --slug <slug> --json
95
+ coauthor export wordpress <id> --yes --json
93
96
  ```
94
97
 
95
98
  ## Credits
package/dist/commands.js CHANGED
@@ -43,6 +43,8 @@ export async function runCommand(input, context) {
43
43
  return runSourceCommand(action, input, context.client);
44
44
  if (scope === 'draft')
45
45
  return runDraftCommand(action, input, context);
46
+ if (scope === 'post-details')
47
+ return runPostDetailsCommand(action, input, context.client);
46
48
  if (scope === 'workflow')
47
49
  return runWorkflowCommand(action, input, context);
48
50
  if (scope === 'credits')
@@ -600,7 +602,17 @@ async function runDraftCommand(action, input, context) {
600
602
  }
601
603
  if (action === 'get') {
602
604
  const format = getString(input.values, 'format');
603
- const data = await client.request({ path: format ? `${basePath}/get?format=${encodeURIComponent(format)}` : `${basePath}/get` });
605
+ const frontmatter = getBoolean(input.values, 'frontmatter');
606
+ if (frontmatter && format?.trim().toLowerCase() !== 'markdown') {
607
+ throw new Error('--frontmatter only applies to --format markdown.');
608
+ }
609
+ const query = new URLSearchParams();
610
+ if (format)
611
+ query.set('format', format);
612
+ if (frontmatter)
613
+ query.set('frontmatter', '1');
614
+ const suffix = query.toString();
615
+ const data = await client.request({ path: suffix ? `${basePath}/get?${suffix}` : `${basePath}/get` });
604
616
  return { ok: true, data };
605
617
  }
606
618
  if (action === 'revise')
@@ -627,6 +639,36 @@ async function runDraftCommand(action, input, context) {
627
639
  }
628
640
  throw new Error('Usage: coauthor draft <generate|status|get|save|revise|revision> <projectId>');
629
641
  }
642
+ const POST_DETAILS_FLAG_FIELDS = [
643
+ ['seo-title', 'seo_title'],
644
+ ['description', 'meta_description'],
645
+ ['slug', 'slug'],
646
+ ['excerpt', 'excerpt'],
647
+ ];
648
+ async function runPostDetailsCommand(action, input, client) {
649
+ const projectId = requireProjectId(input);
650
+ const path = `projects/${encodeURIComponent(projectId)}/post-details`;
651
+ if (!action || action === 'show') {
652
+ const data = await client.request({ path });
653
+ const details = getResponseValue(data, 'post_details');
654
+ return details === null
655
+ ? { ok: true, message: 'This post has no post details. They are generated for drafts created after the feature launched.', data }
656
+ : { ok: true, data };
657
+ }
658
+ if (action === 'set') {
659
+ const body = parseJsonOption(input.values);
660
+ for (const [flag, field] of POST_DETAILS_FLAG_FIELDS) {
661
+ const value = getString(input.values, flag);
662
+ if (value !== undefined)
663
+ body[field] = value.trim() ? value : null;
664
+ }
665
+ if (Object.keys(body).length === 0) {
666
+ throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."]');
667
+ }
668
+ return { ok: true, data: await client.request({ method: 'PATCH', path, body }) };
669
+ }
670
+ throw new Error('Usage: coauthor post-details <show|set> <projectId>');
671
+ }
630
672
  // Revise by instruction: CoAuthor's editor proposes the change, and the
631
673
  // calling agent reviews the groups and applies or discards them.
632
674
  async function runDraftReviseCommand(projectId, input, context) {
@@ -987,6 +1029,12 @@ function exportRequestBody(action, input) {
987
1029
  body.published = status === 'published';
988
1030
  if (description !== undefined)
989
1031
  body.seoDescription = description;
1032
+ const excerpt = getString(input.values, 'excerpt');
1033
+ if (excerpt !== undefined)
1034
+ body.excerpt = excerpt;
1035
+ const seoTitle = getString(input.values, 'seo-title');
1036
+ if (seoTitle !== undefined)
1037
+ body.seoTitle = seoTitle;
990
1038
  return body;
991
1039
  }
992
1040
  // blog
@@ -2504,7 +2552,8 @@ export function helpResult(command = []) {
2504
2552
  ' research run|status|structured',
2505
2553
  ' draft generate|status|get|save|revise',
2506
2554
  ' draft revision show|apply|discard',
2507
- ' draft get supports --format json|markdown|html|text',
2555
+ ' draft get supports --format json|markdown|html|text (--frontmatter adds post details to markdown)',
2556
+ ' post-details show|set',
2508
2557
  ' workflow show|status|advance|run|rewind|approve|resume',
2509
2558
  ' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
2510
2559
  ' image list|status|show|generate|edit|metadata|replace',
@@ -2573,9 +2622,10 @@ function commandHelp(command) {
2573
2622
  'Shows or updates saved primary planning/writing model preferences while preserving fallback order.',
2574
2623
  ].join('\n'),
2575
2624
  'draft get': [
2576
- 'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--json]',
2625
+ 'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--json]',
2577
2626
  '',
2578
2627
  'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
2628
+ '--frontmatter (markdown only) prepends YAML frontmatter from the post details: title, seo_title, description, slug, excerpt, and the featured image. Posts without post details get no frontmatter.',
2579
2629
  ].join('\n'),
2580
2630
  'draft save': [
2581
2631
  'Usage: coauthor draft save <project-id> --data @payload.json [--force] [--json]',
@@ -2699,12 +2749,21 @@ function commandHelp(command) {
2699
2749
  ].join('\n'),
2700
2750
  export: [
2701
2751
  'Usage: coauthor export list <project-id> [--json]',
2702
- ' coauthor export wordpress <project-id> --yes --slug <slug> [--connection-id <id>] [--idempotency-key <key>] [--json]',
2752
+ ' coauthor export wordpress <project-id> --yes [--slug <slug>] [--connection-id <id>] [--idempotency-key <key>] [--json]',
2703
2753
  '',
2704
2754
  'wordpress creates a draft post on the connected WordPress site and returns wordpress_edit_url.',
2755
+ 'Without --slug it uses the post details slug, then the title. A new WordPress post also gets the post details excerpt.',
2705
2756
  'The export prints its operation key; check it with coauthor operation status <key>, or rerun with --idempotency-key <key> to replay safely.',
2706
2757
  'Needs a login with publish permission (coauthor auth login --with-publish). With several sites connected, the error lists their ids for --connection-id.',
2707
2758
  ].join('\n'),
2759
+ 'post-details': [
2760
+ 'Usage: coauthor post-details show <project-id> [--json]',
2761
+ ' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--json]',
2762
+ '',
2763
+ 'Post details are the SEO title, meta description, slug and excerpt CoAuthor writes after a draft. Exports use them as defaults.',
2764
+ 'set changes only the fields you pass; an empty value clears a field. Edited fields are kept when the draft is regenerated.',
2765
+ 'Posts drafted before post details launched have none (show returns post_details: null; set returns post_details_unavailable).',
2766
+ ].join('\n'),
2708
2767
  share: [
2709
2768
  'Usage: coauthor share <project-id> [--json]',
2710
2769
  '',
package/dist/parser.js CHANGED
@@ -52,6 +52,9 @@ const OPTIONS = {
52
52
  slug: { type: 'string' },
53
53
  permalink: { type: 'string' },
54
54
  'connection-id': { type: 'string' },
55
+ excerpt: { type: 'string' },
56
+ 'seo-title': { type: 'string' },
57
+ frontmatter: { type: 'boolean', default: false },
55
58
  status: { type: 'string' },
56
59
  limit: { type: 'string' },
57
60
  cursor: { type: 'string' },
@@ -188,6 +191,8 @@ function commandLength(positionals) {
188
191
  return positionals[2] && ['show', 'apply', 'discard'].includes(positionals[2]) ? 3 : 2;
189
192
  if (first === 'credits')
190
193
  return 1;
194
+ if (first === 'post-details')
195
+ return second && ['show', 'set'].includes(second) ? 2 : 1;
191
196
  if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'slideshow', 'publish', 'export', 'operation'].includes(first ?? ''))
192
197
  return second ? 2 : 1;
193
198
  return 1;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.38",
3
+ "version": "0.0.39",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -56,6 +56,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
56
56
  | `user_recently_editing` | The user is typing in the browser. Wait or ask; use `--force` only with their OK. |
57
57
  | `revision_pending` | Apply or discard the open revision first. |
58
58
  | `revise_unavailable` | Edit the draft directly with `draft get` and `draft save`. |
59
+ | `post_details_unavailable` | The draft predates post details; pass slugs and descriptions to exports directly. |
59
60
  | `coauthor_access_required` | The CoAuthor subscription is inactive. Tell the user. |
60
61
 
61
62
  Everything else, including auth problems: `references/troubleshooting.md`. Credits, plans, and models: `references/credits-and-plans.md`.
@@ -11,6 +11,19 @@ coauthor draft get <id> --format json --json # data.content, the editor do
11
11
 
12
12
  The markdown and HTML have no H1: they start with the featured image (once generated) and then the first section. Add the title yourself from `coauthor project show <id> --json` (`data.project.title`) when you hand over a file. Images appear only after they have been generated, and their URLs are public, so the markdown can be pasted anywhere.
13
13
 
14
+ For a markdown file going into a static-site generator (Astro, Hugo, Next.js, Ghost), add `--frontmatter`: the markdown then starts with a YAML block holding the title, SEO title, meta description, slug, excerpt, and featured image from the post details. Drafts made before post details launched get no frontmatter.
15
+
16
+ ## Post details (SEO title, meta description, slug, excerpt)
17
+
18
+ After a draft, CoAuthor writes the post's SEO title, meta description, slug, and excerpt. Exports use them as defaults, so set them once here rather than on every export.
19
+
20
+ ```sh
21
+ coauthor post-details show <id> --json # data.post_details (null for drafts made before post details launched)
22
+ coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
23
+ ```
24
+
25
+ `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details.
26
+
14
27
  ## Share link (public)
15
28
 
16
29
  `coauthor share <id> --json` returns `data.share_url`, a public read-only page anyone with the link can open. Create one only when the user asks for a link. Calling it again returns the same link.
@@ -21,7 +34,8 @@ Export creates a **draft post** in the user's WordPress site (it is not publishe
21
34
 
22
35
  1. The token needs publish permission. If an export fails with `insufficient_scope`, have the user run `coauthor auth login --with-publish` (in the background with `--no-browser`; they approve in the browser).
23
36
  2. With the user's yes:
24
- `coauthor export wordpress <id> --yes --slug <url-slug> --json`
37
+ `coauthor export wordpress <id> --yes --json`
38
+ The slug comes from the post details (or the title); pass `--slug <url-slug>` to override it. A new WordPress post also gets the post details excerpt.
25
39
  3. `coauthor integrations list --json` shows the connected WordPress sites (`id`, `label`, `site_base_url`, `enabled`) and X accounts. With several sites, ask which one and add `--connection-id <id>` (the error `wordpress_connection_required` lists them too).
26
40
  4. `wordpress_not_connected` means no site is connected yet. The user connects one in CoAuthor's settings (Publishing).
27
41
  5. Give the user `wordpress_edit_url` from the response (also `wordpress_link`) so they can review and publish the post in WordPress.
@@ -30,6 +30,8 @@ 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
+ | `post_details_unavailable` | The draft was made before post details launched, so it has none to edit. | Pass the slug and description to the export directly. |
34
+ | `invalid_post_details` | `post-details set` got something other than text for a field. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`. |
33
35
  | `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
36
  | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
35
37
  | `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
@@ -58,6 +58,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
58
58
  | `user_recently_editing` | The user is typing in the browser. Wait or ask; use `--force` only with their OK. |
59
59
  | `revision_pending` | Apply or discard the open revision first. |
60
60
  | `revise_unavailable` | Edit the draft directly with `draft get` and `draft save`. |
61
+ | `post_details_unavailable` | The draft predates post details; pass slugs and descriptions to exports directly. |
61
62
  | `coauthor_access_required` | The CoAuthor subscription is inactive. Tell the user. |
62
63
 
63
64
  Everything else, including auth problems: `references/troubleshooting.md`. Credits, plans, and models: `references/credits-and-plans.md`.
@@ -375,6 +376,19 @@ coauthor draft get <id> --format json --json # data.content, the editor do
375
376
 
376
377
  The markdown and HTML have no H1: they start with the featured image (once generated) and then the first section. Add the title yourself from `coauthor project show <id> --json` (`data.project.title`) when you hand over a file. Images appear only after they have been generated, and their URLs are public, so the markdown can be pasted anywhere.
377
378
 
379
+ For a markdown file going into a static-site generator (Astro, Hugo, Next.js, Ghost), add `--frontmatter`: the markdown then starts with a YAML block holding the title, SEO title, meta description, slug, excerpt, and featured image from the post details. Drafts made before post details launched get no frontmatter.
380
+
381
+ ### Post details (SEO title, meta description, slug, excerpt)
382
+
383
+ After a draft, CoAuthor writes the post's SEO title, meta description, slug, and excerpt. Exports use them as defaults, so set them once here rather than on every export.
384
+
385
+ ```sh
386
+ coauthor post-details show <id> --json # data.post_details (null for drafts made before post details launched)
387
+ coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
388
+ ```
389
+
390
+ `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details.
391
+
378
392
  ### Share link (public)
379
393
 
380
394
  `coauthor share <id> --json` returns `data.share_url`, a public read-only page anyone with the link can open. Create one only when the user asks for a link. Calling it again returns the same link.
@@ -385,7 +399,8 @@ Export creates a **draft post** in the user's WordPress site (it is not publishe
385
399
 
386
400
  1. The token needs publish permission. If an export fails with `insufficient_scope`, have the user run `coauthor auth login --with-publish` (in the background with `--no-browser`; they approve in the browser).
387
401
  2. With the user's yes:
388
- `coauthor export wordpress <id> --yes --slug <url-slug> --json`
402
+ `coauthor export wordpress <id> --yes --json`
403
+ The slug comes from the post details (or the title); pass `--slug <url-slug>` to override it. A new WordPress post also gets the post details excerpt.
389
404
  3. `coauthor integrations list --json` shows the connected WordPress sites (`id`, `label`, `site_base_url`, `enabled`) and X accounts. With several sites, ask which one and add `--connection-id <id>` (the error `wordpress_connection_required` lists them too).
390
405
  4. `wordpress_not_connected` means no site is connected yet. The user connects one in CoAuthor's settings (Publishing).
391
406
  5. Give the user `wordpress_edit_url` from the response (also `wordpress_link`) so they can review and publish the post in WordPress.
@@ -516,6 +531,8 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
516
531
  | `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. |
517
532
  | `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
518
533
  | `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
534
+ | `post_details_unavailable` | The draft was made before post details launched, so it has none to edit. | Pass the slug and description to the export directly. |
535
+ | `invalid_post_details` | `post-details set` got something other than text for a field. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`. |
519
536
  | `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
537
  | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
521
538
  | `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |