@clickminded/coauthor-cli 0.0.37 → 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 +7 -3
- package/dist/commands.js +162 -13
- package/dist/parser.js +8 -0
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +1 -0
- package/skills/coauthor/references/images-and-social.md +2 -0
- package/skills/coauthor/references/publishing-and-export.md +15 -1
- package/skills/coauthor/references/repurposing.md +4 -0
- package/skills/coauthor/references/troubleshooting.md +4 -0
- package/skills/cursor/coauthor-cli.mdc +26 -1
package/README.md
CHANGED
|
@@ -70,11 +70,15 @@ 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
|
|
77
|
-
coauthor
|
|
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)
|
|
78
82
|
coauthor credits <id> --json
|
|
79
83
|
coauthor integrations list --json # WordPress sites and X accounts
|
|
80
84
|
```
|
|
@@ -88,7 +92,7 @@ Publishing an X thread and exporting to WordPress are real side effects. They ne
|
|
|
88
92
|
```sh
|
|
89
93
|
coauthor auth login --with-publish
|
|
90
94
|
coauthor publish thread <id> --yes --json
|
|
91
|
-
coauthor export wordpress <id> --yes --
|
|
95
|
+
coauthor export wordpress <id> --yes --json
|
|
92
96
|
```
|
|
93
97
|
|
|
94
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
|
|
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) {
|
|
@@ -722,7 +764,7 @@ const DRAFT_SAVE_SHAPE = 'Payload: {"document_id":"<from draft get>","expected_b
|
|
|
722
764
|
// The actions each resource supports on the Agent API. Anything else used to
|
|
723
765
|
// reach the server and come back as "Agent API route not found".
|
|
724
766
|
const RESOURCE_ACTIONS = {
|
|
725
|
-
images: ['list', 'status', 'show', 'generate', 'edit', 'metadata'],
|
|
767
|
+
images: ['list', 'status', 'show', 'generate', 'edit', 'metadata', 'replace'],
|
|
726
768
|
threads: ['list', 'show', 'status', 'generate', 'save', 'create'],
|
|
727
769
|
slideshows: ['list', 'show', 'status', 'generate', 'save'],
|
|
728
770
|
publish: ['thread'],
|
|
@@ -743,6 +785,7 @@ async function runResourceCommand(resource, action, input, client) {
|
|
|
743
785
|
if (!projectId)
|
|
744
786
|
throw new Error(`Missing project id. Usage: coauthor ${name} ${resolvedAction} <project-id> [...]`);
|
|
745
787
|
const basePath = `projects/${encodeURIComponent(projectId)}/${resource}`;
|
|
788
|
+
const artifactQuery = imageArtifactQuery(resource, resolvedAction, input);
|
|
746
789
|
if (resolvedAction === 'list') {
|
|
747
790
|
// These lists return everything for the project; the server has no
|
|
748
791
|
// filters or pages for them, so don't pretend to send any.
|
|
@@ -751,12 +794,12 @@ async function runResourceCommand(resource, action, input, client) {
|
|
|
751
794
|
throw new Error(`${name} list does not support --${flag}; it always returns every ${name === 'export' ? 'export' : 'item'} for the project.`);
|
|
752
795
|
}
|
|
753
796
|
}
|
|
754
|
-
const data = await client.request({ path: basePath });
|
|
797
|
+
const data = await client.request({ path: `${basePath}${artifactQuery}` });
|
|
755
798
|
return { ok: true, data };
|
|
756
799
|
}
|
|
757
800
|
if (resolvedAction === 'show' || resolvedAction === 'status') {
|
|
758
801
|
if (resource === 'images' && resolvedAction === 'status') {
|
|
759
|
-
const data = await client.request({ path: `${basePath}/status` });
|
|
802
|
+
const data = await client.request({ path: `${basePath}/status${artifactQuery}` });
|
|
760
803
|
return { ok: true, data };
|
|
761
804
|
}
|
|
762
805
|
if (resource === 'threads' || resource === 'slideshows') {
|
|
@@ -785,7 +828,10 @@ async function runResourceCommand(resource, action, input, client) {
|
|
|
785
828
|
if (getString(input.values, 'idempotency-key') !== undefined) {
|
|
786
829
|
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
830
|
}
|
|
788
|
-
return generateAllImages(client, projectId, getBoolean(input.values, 'wait'));
|
|
831
|
+
return generateAllImages(client, projectId, getBoolean(input.values, 'wait'), artifactQuery);
|
|
832
|
+
}
|
|
833
|
+
if (resource === 'images' && resolvedAction === 'replace') {
|
|
834
|
+
return replaceImage(client, input, basePath, projectId, resourceId);
|
|
789
835
|
}
|
|
790
836
|
if (resource === 'images' && resolvedAction === 'metadata') {
|
|
791
837
|
if (!resourceId) {
|
|
@@ -866,6 +912,82 @@ async function imageOperationRequest(client, input, projectId, path, body, actio
|
|
|
866
912
|
data,
|
|
867
913
|
};
|
|
868
914
|
}
|
|
915
|
+
const IMAGE_ARTIFACTS = ['article', 'slideshow', 'video'];
|
|
916
|
+
// `--artifact article|slideshow|video` narrows image list/status (and
|
|
917
|
+
// generate --all) to one artifact's placeholders. Without it, every image.
|
|
918
|
+
function imageArtifactQuery(resource, action, input) {
|
|
919
|
+
const artifact = getString(input.values, 'artifact');
|
|
920
|
+
if (artifact === undefined)
|
|
921
|
+
return '';
|
|
922
|
+
const supported = resource === 'images'
|
|
923
|
+
&& (action === 'list' || action === 'status' || (action === 'generate' && getBoolean(input.values, 'all')));
|
|
924
|
+
if (!supported) {
|
|
925
|
+
throw new Error('--artifact works with image list, image status, and image generate --all.');
|
|
926
|
+
}
|
|
927
|
+
const value = artifact.trim().toLowerCase();
|
|
928
|
+
if (!IMAGE_ARTIFACTS.includes(value)) {
|
|
929
|
+
throw new Error(`--artifact must be article, slideshow, or video (got "${artifact}").`);
|
|
930
|
+
}
|
|
931
|
+
return `?artifact=${value}`;
|
|
932
|
+
}
|
|
933
|
+
const REPLACE_IMAGE_MAX_BYTES = 12 * 1024 * 1024;
|
|
934
|
+
const REPLACE_IMAGE_TYPES = {
|
|
935
|
+
png: 'image/png',
|
|
936
|
+
jpg: 'image/jpeg',
|
|
937
|
+
jpeg: 'image/jpeg',
|
|
938
|
+
webp: 'image/webp',
|
|
939
|
+
gif: 'image/gif',
|
|
940
|
+
avif: 'image/avif',
|
|
941
|
+
};
|
|
942
|
+
const REPLACE_USAGE = 'Usage: coauthor image replace <project-id> --placeholder-id <id> (--file <path> | --url <url>) [--json]';
|
|
943
|
+
// Replaces a slideshow or video panel's image with your own. The panel is
|
|
944
|
+
// then marked uploaded: image edit still works, image generate is refused.
|
|
945
|
+
async function replaceImage(client, input, basePath, projectId, positionalId) {
|
|
946
|
+
const placeholderRef = getString(input.values, 'placeholder-id') ?? positionalId;
|
|
947
|
+
if (!placeholderRef)
|
|
948
|
+
throw new Error(`Missing --placeholder-id. ${REPLACE_USAGE}`);
|
|
949
|
+
const file = getString(input.values, 'file');
|
|
950
|
+
const url = getString(input.values, 'url');
|
|
951
|
+
if (file !== undefined && url !== undefined)
|
|
952
|
+
throw new Error(`Pass --file or --url, not both. ${REPLACE_USAGE}`);
|
|
953
|
+
if (!file && !url)
|
|
954
|
+
throw new Error(`Pass the new image with --file <path> or --url <url>. ${REPLACE_USAGE}`);
|
|
955
|
+
let body;
|
|
956
|
+
if (url) {
|
|
957
|
+
if (!/^https?:\/\//i.test(url.trim()))
|
|
958
|
+
throw new Error('--url must be an http or https URL.');
|
|
959
|
+
body = { url: url.trim() };
|
|
960
|
+
}
|
|
961
|
+
else {
|
|
962
|
+
const path = resolve(file);
|
|
963
|
+
const extension = path.split('.').pop()?.toLowerCase() ?? '';
|
|
964
|
+
const contentType = REPLACE_IMAGE_TYPES[extension];
|
|
965
|
+
if (!contentType)
|
|
966
|
+
throw new Error('--file must be a PNG, JPEG, WebP, GIF, or AVIF image (.png, .jpg, .jpeg, .webp, .gif, .avif).');
|
|
967
|
+
let bytes;
|
|
968
|
+
try {
|
|
969
|
+
bytes = await readFile(path);
|
|
970
|
+
}
|
|
971
|
+
catch {
|
|
972
|
+
throw new Error(`Could not read --file ${file}.`);
|
|
973
|
+
}
|
|
974
|
+
if (bytes.length === 0)
|
|
975
|
+
throw new Error(`--file ${file} is empty.`);
|
|
976
|
+
if (bytes.length > REPLACE_IMAGE_MAX_BYTES)
|
|
977
|
+
throw new Error(`--file ${file} is too large (max 12 MB).`);
|
|
978
|
+
body = { data: bytes.toString('base64'), content_type: contentType, filename: basename(path) };
|
|
979
|
+
}
|
|
980
|
+
const data = await client.request({
|
|
981
|
+
method: 'POST',
|
|
982
|
+
path: `${basePath}/${encodeURIComponent(placeholderRef)}/replace`,
|
|
983
|
+
body,
|
|
984
|
+
});
|
|
985
|
+
return {
|
|
986
|
+
ok: true,
|
|
987
|
+
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`,
|
|
988
|
+
data,
|
|
989
|
+
};
|
|
990
|
+
}
|
|
869
991
|
// Publish and export run as recorded operations keyed by the Idempotency-Key.
|
|
870
992
|
// Print the key so the caller can look the outcome up (`operation status`) or
|
|
871
993
|
// replay the same request safely with --idempotency-key.
|
|
@@ -907,6 +1029,12 @@ function exportRequestBody(action, input) {
|
|
|
907
1029
|
body.published = status === 'published';
|
|
908
1030
|
if (description !== undefined)
|
|
909
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;
|
|
910
1038
|
return body;
|
|
911
1039
|
}
|
|
912
1040
|
// blog
|
|
@@ -2175,8 +2303,8 @@ function imageStatusRows(data) {
|
|
|
2175
2303
|
// Generates every planned image that isn't already done or generating, then
|
|
2176
2304
|
// optionally waits (under the 10-minute agent shell limit) until none are
|
|
2177
2305
|
// still generating.
|
|
2178
|
-
async function generateAllImages(client, projectId, wait) {
|
|
2179
|
-
const statusPath = `projects/${encodeURIComponent(projectId)}/images/status`;
|
|
2306
|
+
async function generateAllImages(client, projectId, wait, artifactQuery = '') {
|
|
2307
|
+
const statusPath = `projects/${encodeURIComponent(projectId)}/images/status${artifactQuery}`;
|
|
2180
2308
|
const before = imageStatusRows(await client.request({ path: statusPath }));
|
|
2181
2309
|
const toGenerate = before.filter((row) => row.status !== 'done' && row.status !== 'generating');
|
|
2182
2310
|
const started = [];
|
|
@@ -2424,10 +2552,11 @@ export function helpResult(command = []) {
|
|
|
2424
2552
|
' research run|status|structured',
|
|
2425
2553
|
' draft generate|status|get|save|revise',
|
|
2426
2554
|
' draft revision show|apply|discard',
|
|
2427
|
-
' 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',
|
|
2428
2557
|
' workflow show|status|advance|run|rewind|approve|resume',
|
|
2429
2558
|
' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
|
|
2430
|
-
' image list|status|show|generate|edit|metadata',
|
|
2559
|
+
' image list|status|show|generate|edit|metadata|replace',
|
|
2431
2560
|
' thread list|show|create|generate|save',
|
|
2432
2561
|
' slideshow show|save',
|
|
2433
2562
|
' publish thread (supports --idempotency-key)',
|
|
@@ -2493,9 +2622,10 @@ function commandHelp(command) {
|
|
|
2493
2622
|
'Shows or updates saved primary planning/writing model preferences while preserving fallback order.',
|
|
2494
2623
|
].join('\n'),
|
|
2495
2624
|
'draft get': [
|
|
2496
|
-
'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]',
|
|
2497
2626
|
'',
|
|
2498
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.',
|
|
2499
2629
|
].join('\n'),
|
|
2500
2630
|
'draft save': [
|
|
2501
2631
|
'Usage: coauthor draft save <project-id> --data @payload.json [--force] [--json]',
|
|
@@ -2597,11 +2727,13 @@ function commandHelp(command) {
|
|
|
2597
2727
|
"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
2728
|
].join('\n'),
|
|
2599
2729
|
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)',
|
|
2730
|
+
'Usage: coauthor image <list|status|show|generate|edit|metadata|replace> <project-id> [...] [--json]',
|
|
2731
|
+
' coauthor image generate <project-id> --all [--artifact <kind>] [--wait] [--json] (every planned image; --wait until they finish)',
|
|
2602
2732
|
'',
|
|
2603
2733
|
'list: planned placeholders. generate/edit: --placeholder-id <id or placeholder_id> [--edit-prompt "..."]. status: generation progress.',
|
|
2734
|
+
'list/status: --artifact article|slideshow|video shows one artifact\'s images (each carries artifact, slot and source).',
|
|
2604
2735
|
'metadata <project-id> <placeholder id>: --alt-text, --description, --file-slug.',
|
|
2736
|
+
'replace <project-id> --placeholder-id <id> (--file <path> | --url <url>): use your own image for a slideshow or video panel.',
|
|
2605
2737
|
].join('\n'),
|
|
2606
2738
|
thread: [
|
|
2607
2739
|
'Usage: coauthor thread <show|generate|save> <project-id> [--data <json|@file>] [--writing-model <id>] [--json]',
|
|
@@ -2617,12 +2749,21 @@ function commandHelp(command) {
|
|
|
2617
2749
|
].join('\n'),
|
|
2618
2750
|
export: [
|
|
2619
2751
|
'Usage: coauthor export list <project-id> [--json]',
|
|
2620
|
-
' 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]',
|
|
2621
2753
|
'',
|
|
2622
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.',
|
|
2623
2756
|
'The export prints its operation key; check it with coauthor operation status <key>, or rerun with --idempotency-key <key> to replay safely.',
|
|
2624
2757
|
'Needs a login with publish permission (coauthor auth login --with-publish). With several sites connected, the error lists their ids for --connection-id.',
|
|
2625
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'),
|
|
2626
2767
|
share: [
|
|
2627
2768
|
'Usage: coauthor share <project-id> [--json]',
|
|
2628
2769
|
'',
|
|
@@ -2669,6 +2810,14 @@ function commandHelp(command) {
|
|
|
2669
2810
|
'Prints an operation key (data.idempotency_key in --json): coauthor operation status <key> reports the finished image url or the error.',
|
|
2670
2811
|
'--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
2812
|
].join('\n'),
|
|
2813
|
+
'image replace': [
|
|
2814
|
+
REPLACE_USAGE,
|
|
2815
|
+
'',
|
|
2816
|
+
'Replaces a slideshow or video panel\'s image with your own (PNG, JPEG, WebP, GIF or AVIF, up to 12 MB).',
|
|
2817
|
+
'Find panels with coauthor image list <project-id> --artifact slideshow (or video); pass the placeholder id or placeholder_id.',
|
|
2818
|
+
'The panel is then marked uploaded (source: "uploaded"): image edit still works, image generate is refused (uploaded_image),',
|
|
2819
|
+
'and restyling panels skips it. Article and featured images cannot be replaced here.',
|
|
2820
|
+
].join('\n'),
|
|
2672
2821
|
'image edit': [
|
|
2673
2822
|
'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--json]',
|
|
2674
2823
|
'',
|
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' },
|
|
@@ -77,6 +80,9 @@ const OPTIONS = {
|
|
|
77
80
|
accept: { type: 'string' },
|
|
78
81
|
reject: { type: 'string' },
|
|
79
82
|
'idempotency-key': { type: 'string' },
|
|
83
|
+
file: { type: 'string' },
|
|
84
|
+
url: { type: 'string' },
|
|
85
|
+
artifact: { type: 'string' },
|
|
80
86
|
};
|
|
81
87
|
/** True when `--name` (or its short alias) consumes the next argv entry as its value. */
|
|
82
88
|
export function optionTakesValue(flag) {
|
|
@@ -185,6 +191,8 @@ function commandLength(positionals) {
|
|
|
185
191
|
return positionals[2] && ['show', 'apply', 'discard'].includes(positionals[2]) ? 3 : 2;
|
|
186
192
|
if (first === 'credits')
|
|
187
193
|
return 1;
|
|
194
|
+
if (first === 'post-details')
|
|
195
|
+
return second && ['show', 'set'].includes(second) ? 2 : 1;
|
|
188
196
|
if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'slideshow', 'publish', 'export', 'operation'].includes(first ?? ''))
|
|
189
197
|
return second ? 2 : 1;
|
|
190
198
|
return 1;
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -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`.
|
|
@@ -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.
|
|
@@ -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 --
|
|
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.
|
|
@@ -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:
|
|
@@ -30,7 +30,11 @@ 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 "..."`. |
|
|
36
|
+
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
37
|
+
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|
|
34
38
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
35
39
|
| `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
40
|
|
|
@@ -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`.
|
|
@@ -343,6 +344,8 @@ Draft generation plans image placeholders, including a featured image (`is_featu
|
|
|
343
344
|
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
344
345
|
- Prices, dates, and text inside the image must match the article.
|
|
345
346
|
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`).
|
|
347
|
+
- 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.
|
|
348
|
+
- `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
349
|
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
350
|
|
|
348
351
|
Images cost credits each time they are generated or edited, so check the brief and placeholder purpose before regenerating.
|
|
@@ -373,6 +376,19 @@ coauthor draft get <id> --format json --json # data.content, the editor do
|
|
|
373
376
|
|
|
374
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.
|
|
375
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
|
+
|
|
376
392
|
### Share link (public)
|
|
377
393
|
|
|
378
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.
|
|
@@ -383,7 +399,8 @@ Export creates a **draft post** in the user's WordPress site (it is not publishe
|
|
|
383
399
|
|
|
384
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).
|
|
385
401
|
2. With the user's yes:
|
|
386
|
-
`coauthor export wordpress <id> --yes --
|
|
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.
|
|
387
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).
|
|
388
405
|
4. `wordpress_not_connected` means no site is connected yet. The user connects one in CoAuthor's settings (Publishing).
|
|
389
406
|
5. Give the user `wordpress_edit_url` from the response (also `wordpress_link`) so they can review and publish the post in WordPress.
|
|
@@ -454,6 +471,8 @@ A carousel of 1080x1350 slides (for LinkedIn or Instagram) with illustrated pane
|
|
|
454
471
|
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
472
|
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
473
|
|
|
474
|
+
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.
|
|
475
|
+
|
|
457
476
|
The server draws the slides with the Inter font, so line breaks can differ slightly from the web app's own PNG download.
|
|
458
477
|
|
|
459
478
|
### Video
|
|
@@ -465,6 +484,8 @@ A short vertical video (1080x1920) of the article's key points, with illustrated
|
|
|
465
484
|
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
485
|
4. `coauthor repurpose download <id> --format video --out <dir>` saves `video-<variant>.mp4`.
|
|
467
486
|
|
|
487
|
+
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.
|
|
488
|
+
|
|
468
489
|
### Deliver
|
|
469
490
|
|
|
470
491
|
`coauthor repurpose download <id> --out <dir>` writes:
|
|
@@ -510,7 +531,11 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
510
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. |
|
|
511
532
|
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
512
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`. |
|
|
513
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 "..."`. |
|
|
537
|
+
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
538
|
+
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|
|
514
539
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
515
540
|
| `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
541
|
|