@clickminded/coauthor-cli 0.0.7 → 0.0.9
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 +5 -1
- package/dist/commands.js +200 -12
- package/dist/index.js +67 -2
- package/dist/parser.js +2 -0
- package/package.json +3 -1
- package/scripts/postinstall.mjs +96 -0
- package/skills/agents/SKILL.md +55 -0
- package/skills/claude/SKILL.md +10 -1
- package/skills/codex/SKILL.md +10 -1
- package/skills/cursor/coauthor-cli.mdc +5 -0
package/README.md
CHANGED
|
@@ -91,6 +91,7 @@ Install one target at a time:
|
|
|
91
91
|
coauthor skills install codex
|
|
92
92
|
coauthor skills install claude
|
|
93
93
|
coauthor skills install cursor
|
|
94
|
+
coauthor skills install agents
|
|
94
95
|
```
|
|
95
96
|
|
|
96
97
|
Default install paths are:
|
|
@@ -98,8 +99,11 @@ Default install paths are:
|
|
|
98
99
|
- Codex: `~/.codex/skills/coauthor/SKILL.md`
|
|
99
100
|
- Claude: `./.claude/skills/coauthor/SKILL.md`
|
|
100
101
|
- Cursor: `./.cursor/rules/coauthor-cli.mdc`
|
|
102
|
+
- Agents: `./.agents/skills/coauthor/SKILL.md`
|
|
101
103
|
|
|
102
|
-
Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install Claude/Cursor skills into a specific project.
|
|
104
|
+
Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install project-local Claude/Cursor/Agents skills into a specific project.
|
|
105
|
+
|
|
106
|
+
Skill installs are recorded in `~/.config/coauthor/managed-skills.json`. Future npm package updates automatically refresh recorded skill files when they still match the previously installed template. If you edit a skill file by hand, the auto-update leaves it alone until you run `coauthor skills install <target> --force`.
|
|
103
107
|
|
|
104
108
|
## Common Commands
|
|
105
109
|
|
package/dist/commands.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { setTimeout as sleep } from 'node:timers/promises';
|
|
2
2
|
import { spawn } from 'node:child_process';
|
|
3
|
+
import { createHash } from 'node:crypto';
|
|
3
4
|
import { mkdir, readFile, writeFile } from 'node:fs/promises';
|
|
4
5
|
import { homedir } from 'node:os';
|
|
5
6
|
import { dirname, join, resolve } from 'node:path';
|
|
@@ -18,7 +19,7 @@ export async function runCommand(input, context) {
|
|
|
18
19
|
if (scope === 'workspace')
|
|
19
20
|
return runWorkspaceCommand(action, input, context.client);
|
|
20
21
|
if (scope === 'chat')
|
|
21
|
-
return runChatCommand(input, context.client);
|
|
22
|
+
return runChatCommand(action, input, context.client);
|
|
22
23
|
if (scope === 'contract')
|
|
23
24
|
return runArtifactCommand('contract', action, input, context.client);
|
|
24
25
|
if (scope === 'outline')
|
|
@@ -164,19 +165,37 @@ async function runWorkspaceCommand(action, input, client) {
|
|
|
164
165
|
const data = await client.request({ path: `projects/${encodeURIComponent(projectId)}/workspace` });
|
|
165
166
|
return { ok: true, data };
|
|
166
167
|
}
|
|
167
|
-
async function runChatCommand(input, client) {
|
|
168
|
+
async function runChatCommand(action, input, client) {
|
|
169
|
+
if (action === 'show' || action === 'list') {
|
|
170
|
+
const projectId = requireProjectId(input);
|
|
171
|
+
const data = await client.request({ path: `projects/${encodeURIComponent(projectId)}/workspace` });
|
|
172
|
+
return {
|
|
173
|
+
ok: true,
|
|
174
|
+
data: {
|
|
175
|
+
project_id: projectId,
|
|
176
|
+
workspace_chat_id: extractNestedString(data, ['workspaceChatId']) ?? null,
|
|
177
|
+
messages: extractNestedValue(data, ['messages']) ?? [],
|
|
178
|
+
},
|
|
179
|
+
};
|
|
180
|
+
}
|
|
168
181
|
const projectId = requireProjectId(input);
|
|
169
182
|
const message = getString(input.values, 'message') ?? input.positionals.slice(1).join(' ');
|
|
170
183
|
if (!message)
|
|
171
184
|
throw new Error('Usage: coauthor chat <projectId> --message "..."');
|
|
172
185
|
const body = withNamedOptions(parseJsonOption(input.values), input.values, ['stage', 'execution-token']);
|
|
186
|
+
const stage = getString(input.values, 'stage');
|
|
187
|
+
if (stage)
|
|
188
|
+
body.activeArtifact = stage;
|
|
173
189
|
body.message = message;
|
|
174
190
|
const data = await client.request({
|
|
175
191
|
method: 'POST',
|
|
176
192
|
path: `projects/${encodeURIComponent(projectId)}/chat`,
|
|
177
193
|
body,
|
|
178
194
|
});
|
|
179
|
-
return {
|
|
195
|
+
return {
|
|
196
|
+
ok: true,
|
|
197
|
+
data: enrichChatResult(data, projectId, stage),
|
|
198
|
+
};
|
|
180
199
|
}
|
|
181
200
|
async function runWorkflowCommand(action, input, client) {
|
|
182
201
|
const projectId = requireProjectId(input);
|
|
@@ -249,7 +268,9 @@ async function runArtifactCommand(artifact, action, input, client) {
|
|
|
249
268
|
return { ok: true, data };
|
|
250
269
|
}
|
|
251
270
|
if (action === 'generate' || action === 'save' || action === 'approve') {
|
|
252
|
-
const body =
|
|
271
|
+
const body = action === 'approve'
|
|
272
|
+
? await buildArtifactApproveBody(artifact, input, client, basePath)
|
|
273
|
+
: withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
|
|
253
274
|
const path = action === 'save' ? basePath : `${basePath}/${action}`;
|
|
254
275
|
const data = await client.request({ method: 'POST', path, body });
|
|
255
276
|
return { ok: true, data };
|
|
@@ -268,7 +289,7 @@ async function runResearchCommand(action, input, client) {
|
|
|
268
289
|
return { ok: true, data };
|
|
269
290
|
}
|
|
270
291
|
if (action === 'status') {
|
|
271
|
-
return { ok: true, data: await client.request({ path: `${basePath}/status` }) };
|
|
292
|
+
return { ok: true, data: enrichResearchStatus(await client.request({ path: `${basePath}/status` })) };
|
|
272
293
|
}
|
|
273
294
|
if (action === 'structured') {
|
|
274
295
|
return { ok: true, data: await client.request({ path: `${basePath}/structured` }) };
|
|
@@ -380,11 +401,12 @@ async function runOperationCommand(action, input, client) {
|
|
|
380
401
|
}
|
|
381
402
|
throw new Error('Usage: coauthor operation <list|show|status>');
|
|
382
403
|
}
|
|
383
|
-
const SKILL_NAMES = ['codex', 'claude', 'cursor'];
|
|
404
|
+
const SKILL_NAMES = ['codex', 'claude', 'cursor', 'agents'];
|
|
384
405
|
const SKILL_TEMPLATE_PATHS = {
|
|
385
406
|
codex: '../skills/codex/SKILL.md',
|
|
386
407
|
claude: '../skills/claude/SKILL.md',
|
|
387
408
|
cursor: '../skills/cursor/coauthor-cli.mdc',
|
|
409
|
+
agents: '../skills/agents/SKILL.md',
|
|
388
410
|
};
|
|
389
411
|
async function runSkillsCommand(action, input) {
|
|
390
412
|
if (!action || action === 'list') {
|
|
@@ -415,41 +437,112 @@ async function runSkillsCommand(action, input) {
|
|
|
415
437
|
data: { results },
|
|
416
438
|
};
|
|
417
439
|
}
|
|
418
|
-
throw new Error('Usage: coauthor skills <list|install> [codex|claude|cursor|all]');
|
|
440
|
+
throw new Error('Usage: coauthor skills <list|install> [codex|claude|cursor|agents|all]');
|
|
419
441
|
}
|
|
420
442
|
function resolveRequestedSkills(value) {
|
|
421
443
|
if (!value || value === 'all')
|
|
422
444
|
return [...SKILL_NAMES];
|
|
423
445
|
if (isSkillName(value))
|
|
424
446
|
return [value];
|
|
425
|
-
throw new Error('Usage: coauthor skills install <codex|claude|cursor|all>');
|
|
447
|
+
throw new Error('Usage: coauthor skills install <codex|claude|cursor|agents|all>');
|
|
426
448
|
}
|
|
427
449
|
function isSkillName(value) {
|
|
428
450
|
return SKILL_NAMES.includes(value);
|
|
429
451
|
}
|
|
430
452
|
async function installSkill(params) {
|
|
431
453
|
const targetPath = getSkillInstallPath(params.skill, params.cwd);
|
|
454
|
+
const templatePath = getSkillTemplatePath(params.skill);
|
|
455
|
+
const template = await readFile(templatePath, 'utf8');
|
|
456
|
+
const templateHash = sha256(template);
|
|
432
457
|
if (!params.force && await fileExists(targetPath)) {
|
|
458
|
+
const current = await readFile(targetPath, 'utf8');
|
|
459
|
+
if (sha256(current) === templateHash) {
|
|
460
|
+
await recordManagedSkill({
|
|
461
|
+
skill: params.skill,
|
|
462
|
+
path: targetPath,
|
|
463
|
+
template: getSkillTemplateRelativePath(params.skill),
|
|
464
|
+
templateHash,
|
|
465
|
+
});
|
|
466
|
+
}
|
|
433
467
|
return { skill: params.skill, status: 'skipped', path: targetPath };
|
|
434
468
|
}
|
|
435
469
|
if (params.dryRun) {
|
|
436
470
|
return { skill: params.skill, status: 'dry_run', path: targetPath };
|
|
437
471
|
}
|
|
438
|
-
const template = await readFile(getSkillTemplatePath(params.skill), 'utf8');
|
|
439
472
|
await mkdir(dirname(targetPath), { recursive: true });
|
|
440
473
|
await writeFile(targetPath, template, { mode: 0o644 });
|
|
474
|
+
await recordManagedSkill({
|
|
475
|
+
skill: params.skill,
|
|
476
|
+
path: targetPath,
|
|
477
|
+
template: getSkillTemplateRelativePath(params.skill),
|
|
478
|
+
templateHash,
|
|
479
|
+
});
|
|
441
480
|
return { skill: params.skill, status: 'installed', path: targetPath };
|
|
442
481
|
}
|
|
443
482
|
function getSkillTemplatePath(skill) {
|
|
444
|
-
return fileURLToPath(new URL(
|
|
483
|
+
return fileURLToPath(new URL(getSkillTemplateRelativePath(skill), import.meta.url));
|
|
484
|
+
}
|
|
485
|
+
function getSkillTemplateRelativePath(skill) {
|
|
486
|
+
return SKILL_TEMPLATE_PATHS[skill];
|
|
445
487
|
}
|
|
446
488
|
function getSkillInstallPath(skill, cwd) {
|
|
447
489
|
if (skill === 'codex')
|
|
448
490
|
return join(homedir(), '.codex', 'skills', 'coauthor', 'SKILL.md');
|
|
449
491
|
if (skill === 'claude')
|
|
450
492
|
return join(cwd, '.claude', 'skills', 'coauthor', 'SKILL.md');
|
|
493
|
+
if (skill === 'agents')
|
|
494
|
+
return join(cwd, '.agents', 'skills', 'coauthor', 'SKILL.md');
|
|
451
495
|
return join(cwd, '.cursor', 'rules', 'coauthor-cli.mdc');
|
|
452
496
|
}
|
|
497
|
+
async function recordManagedSkill(entry) {
|
|
498
|
+
const registry = await readManagedSkillRegistry();
|
|
499
|
+
const existing = registry.skills.findIndex((skill) => skill.path === entry.path);
|
|
500
|
+
const next = {
|
|
501
|
+
...entry,
|
|
502
|
+
updatedAt: new Date().toISOString(),
|
|
503
|
+
};
|
|
504
|
+
if (existing >= 0) {
|
|
505
|
+
registry.skills[existing] = next;
|
|
506
|
+
}
|
|
507
|
+
else {
|
|
508
|
+
registry.skills.push(next);
|
|
509
|
+
}
|
|
510
|
+
const registryPath = getManagedSkillRegistryPath();
|
|
511
|
+
await mkdir(dirname(registryPath), { recursive: true });
|
|
512
|
+
await writeFile(registryPath, `${JSON.stringify(registry, null, 2)}\n`, { mode: 0o644 });
|
|
513
|
+
}
|
|
514
|
+
async function readManagedSkillRegistry() {
|
|
515
|
+
try {
|
|
516
|
+
const raw = await readFile(getManagedSkillRegistryPath(), 'utf8');
|
|
517
|
+
const parsed = JSON.parse(raw);
|
|
518
|
+
if (parsed.version !== 1 || !Array.isArray(parsed.skills)) {
|
|
519
|
+
return { version: 1, skills: [] };
|
|
520
|
+
}
|
|
521
|
+
return {
|
|
522
|
+
version: 1,
|
|
523
|
+
skills: parsed.skills.filter((skill) => {
|
|
524
|
+
return Boolean(skill)
|
|
525
|
+
&& isSkillName(skill.skill)
|
|
526
|
+
&& typeof skill.path === 'string'
|
|
527
|
+
&& typeof skill.template === 'string'
|
|
528
|
+
&& typeof skill.templateHash === 'string';
|
|
529
|
+
}),
|
|
530
|
+
};
|
|
531
|
+
}
|
|
532
|
+
catch (error) {
|
|
533
|
+
if (isMissingFileError(error))
|
|
534
|
+
return { version: 1, skills: [] };
|
|
535
|
+
throw error;
|
|
536
|
+
}
|
|
537
|
+
}
|
|
538
|
+
function sha256(value) {
|
|
539
|
+
return createHash('sha256').update(value).digest('hex');
|
|
540
|
+
}
|
|
541
|
+
function getManagedSkillRegistryPath() {
|
|
542
|
+
return process.env.COAUTHOR_MANAGED_SKILLS_REGISTRY
|
|
543
|
+
? resolve(process.env.COAUTHOR_MANAGED_SKILLS_REGISTRY)
|
|
544
|
+
: join(homedir(), '.config', 'coauthor', 'managed-skills.json');
|
|
545
|
+
}
|
|
453
546
|
async function fileExists(path) {
|
|
454
547
|
try {
|
|
455
548
|
await readFile(path);
|
|
@@ -579,6 +672,9 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
|
579
672
|
let latestResearch = null;
|
|
580
673
|
let draftGenerate = null;
|
|
581
674
|
let attemptedDraftStart = false;
|
|
675
|
+
if (workflowIndicatesBackgroundResearch(initialData)) {
|
|
676
|
+
return researchRunningWorkflowResult(projectId, initialData, null, null);
|
|
677
|
+
}
|
|
582
678
|
while (Date.now() < deadline) {
|
|
583
679
|
await sleep(3000);
|
|
584
680
|
latestDraft = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
@@ -645,6 +741,93 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
|
645
741
|
},
|
|
646
742
|
};
|
|
647
743
|
}
|
|
744
|
+
async function buildArtifactApproveBody(artifact, input, client, basePath) {
|
|
745
|
+
const explicitBody = parseJsonOption(input.values);
|
|
746
|
+
const body = withNamedOptions(explicitBody, input.values, ['execution-token']);
|
|
747
|
+
if (getString(input.values, 'data') !== undefined)
|
|
748
|
+
return body;
|
|
749
|
+
const current = await client.request({ path: basePath });
|
|
750
|
+
const payloadHash = extractNestedString(current, ['metadata', 'payload_hash']);
|
|
751
|
+
if (payloadHash)
|
|
752
|
+
body.expectedPayloadHash = payloadHash;
|
|
753
|
+
if (artifact === 'contract') {
|
|
754
|
+
const contract = extractNestedValue(current, ['artifact']);
|
|
755
|
+
if (contract && typeof contract === 'object' && !Array.isArray(contract)) {
|
|
756
|
+
body.contract = contract;
|
|
757
|
+
}
|
|
758
|
+
return body;
|
|
759
|
+
}
|
|
760
|
+
if (artifact === 'outline') {
|
|
761
|
+
const sections = extractNestedValue(current, ['artifact']);
|
|
762
|
+
if (!Array.isArray(sections) || sections.length === 0) {
|
|
763
|
+
throw new Error('Generate or save an outline before approving it.');
|
|
764
|
+
}
|
|
765
|
+
body.sections = sections;
|
|
766
|
+
return body;
|
|
767
|
+
}
|
|
768
|
+
const researchTasks = extractNestedValue(current, ['artifact']);
|
|
769
|
+
if (!Array.isArray(researchTasks) || researchTasks.length === 0) {
|
|
770
|
+
throw new Error('Generate or save a research plan before approving it.');
|
|
771
|
+
}
|
|
772
|
+
body.researchTasks = researchTasks;
|
|
773
|
+
return body;
|
|
774
|
+
}
|
|
775
|
+
function enrichChatResult(data, projectId, stage) {
|
|
776
|
+
if (!data || typeof data !== 'object' || Array.isArray(data))
|
|
777
|
+
return data;
|
|
778
|
+
const result = {
|
|
779
|
+
...data,
|
|
780
|
+
transcript_command: `coauthor chat show ${projectId} --json`,
|
|
781
|
+
};
|
|
782
|
+
if (stage?.trim().toLowerCase() === 'draft') {
|
|
783
|
+
result.draft_saved = false;
|
|
784
|
+
result.draft_note = 'Draft-stage chat responses are saved to the workspace chat transcript, not to the draft document. Use transcript_command to retrieve the response.';
|
|
785
|
+
}
|
|
786
|
+
return result;
|
|
787
|
+
}
|
|
788
|
+
function enrichResearchStatus(data) {
|
|
789
|
+
if (!data || typeof data !== 'object' || Array.isArray(data))
|
|
790
|
+
return data;
|
|
791
|
+
const runStatus = extractNestedString(data, ['run', 'status']);
|
|
792
|
+
const projectState = getResponseString(data, 'project_state');
|
|
793
|
+
if (runStatus !== 'running' || projectState === 'research_running')
|
|
794
|
+
return data;
|
|
795
|
+
return {
|
|
796
|
+
...data,
|
|
797
|
+
diagnostic: {
|
|
798
|
+
code: 'research_run_state_mismatch',
|
|
799
|
+
message: `Latest research run is still running while project_state is "${projectState ?? 'unknown'}".`,
|
|
800
|
+
recovery_commands: [
|
|
801
|
+
'coauthor research status <project-id> --json',
|
|
802
|
+
'coauthor workflow resume <project-id> --target research --wait --json',
|
|
803
|
+
'coauthor workflow rewind <project-id> --target research --json',
|
|
804
|
+
],
|
|
805
|
+
},
|
|
806
|
+
};
|
|
807
|
+
}
|
|
808
|
+
function workflowIndicatesBackgroundResearch(data) {
|
|
809
|
+
if (!data || typeof data !== 'object' || Array.isArray(data))
|
|
810
|
+
return false;
|
|
811
|
+
return getResponseString(data, 'project_state') === 'research_running'
|
|
812
|
+
|| getResponseString(data, 'status') === 'research_running';
|
|
813
|
+
}
|
|
814
|
+
function researchRunningWorkflowResult(projectId, workflow, researchStatus, draftStatus) {
|
|
815
|
+
return {
|
|
816
|
+
ok: true,
|
|
817
|
+
status: 'research_running',
|
|
818
|
+
message: 'Research is running in the background. Draft generation has not started yet.',
|
|
819
|
+
data: {
|
|
820
|
+
workflow,
|
|
821
|
+
research_status: researchStatus,
|
|
822
|
+
draft_status: draftStatus,
|
|
823
|
+
next_commands: [
|
|
824
|
+
`coauthor research status ${projectId} --json`,
|
|
825
|
+
`coauthor workflow resume ${projectId} --target draft --wait --json`,
|
|
826
|
+
`coauthor workflow rewind ${projectId} --target research --json`,
|
|
827
|
+
],
|
|
828
|
+
},
|
|
829
|
+
};
|
|
830
|
+
}
|
|
648
831
|
function requiresKeyPauseResult(projectId, target, message, data) {
|
|
649
832
|
const resumeCommand = `coauthor workflow resume ${projectId} --target ${target} --wait --json`;
|
|
650
833
|
return {
|
|
@@ -658,13 +841,17 @@ function requiresKeyPauseResult(projectId, target, message, data) {
|
|
|
658
841
|
};
|
|
659
842
|
}
|
|
660
843
|
function extractNestedString(value, path) {
|
|
844
|
+
const current = extractNestedValue(value, path);
|
|
845
|
+
return typeof current === 'string' ? current : undefined;
|
|
846
|
+
}
|
|
847
|
+
function extractNestedValue(value, path) {
|
|
661
848
|
let current = value;
|
|
662
849
|
for (const key of path) {
|
|
663
850
|
if (!current || typeof current !== 'object' || Array.isArray(current))
|
|
664
851
|
return undefined;
|
|
665
852
|
current = current[key];
|
|
666
853
|
}
|
|
667
|
-
return
|
|
854
|
+
return current;
|
|
668
855
|
}
|
|
669
856
|
function normalizeWorkflowWaitTarget(value) {
|
|
670
857
|
if (!value)
|
|
@@ -718,7 +905,7 @@ export function helpResult() {
|
|
|
718
905
|
' auth login|status|logout',
|
|
719
906
|
' project create|list|show',
|
|
720
907
|
' workspace show',
|
|
721
|
-
' chat',
|
|
908
|
+
' chat [show|list]',
|
|
722
909
|
' contract show|save|approve',
|
|
723
910
|
' outline show|generate|save|approve',
|
|
724
911
|
' research-plan show|generate|save|approve',
|
|
@@ -734,6 +921,7 @@ export function helpResult() {
|
|
|
734
921
|
' operation list|show|status',
|
|
735
922
|
' credits',
|
|
736
923
|
' skills list|install',
|
|
924
|
+
' skills install supports codex|claude|cursor|agents|all',
|
|
737
925
|
].join('\n'),
|
|
738
926
|
};
|
|
739
927
|
}
|
package/dist/index.js
CHANGED
|
@@ -30,21 +30,86 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
30
30
|
}
|
|
31
31
|
catch (error) {
|
|
32
32
|
const wantsJson = argv.includes('--json');
|
|
33
|
-
const formatted = formatCliError(error, resolvedBaseUrl);
|
|
33
|
+
const formatted = formatCliError(error, resolvedBaseUrl, argv);
|
|
34
34
|
process.stderr.write(renderError(formatted.result ?? formatted.error, wantsJson));
|
|
35
35
|
return formatted.exitCode;
|
|
36
36
|
}
|
|
37
37
|
}
|
|
38
|
-
function formatCliError(error, baseUrl) {
|
|
38
|
+
function formatCliError(error, baseUrl, argv = []) {
|
|
39
39
|
if (error instanceof AgentHttpError) {
|
|
40
40
|
const requiresKey = formatRequiresKeyResult(error.responseBody, baseUrl);
|
|
41
41
|
if (requiresKey)
|
|
42
42
|
return { error: new Error(requiresKey.message), result: requiresKey, exitCode: 2 };
|
|
43
43
|
const message = extractErrorMessage(error.responseBody) ?? error.message;
|
|
44
|
+
const researchBlock = formatResearchRunningDraftBlock(message, argv);
|
|
45
|
+
if (researchBlock)
|
|
46
|
+
return { error: new Error(researchBlock.message), result: researchBlock, exitCode: 2 };
|
|
44
47
|
return { error: new Error(message), exitCode: 1 };
|
|
45
48
|
}
|
|
46
49
|
return { error: error instanceof Error ? error : new Error(String(error)), exitCode: 1 };
|
|
47
50
|
}
|
|
51
|
+
function formatResearchRunningDraftBlock(message, argv) {
|
|
52
|
+
if (!/Cannot generate draft in state "research_running"/i.test(message))
|
|
53
|
+
return null;
|
|
54
|
+
const projectId = resolveProjectIdFromArgv(argv);
|
|
55
|
+
const recoveryCommands = projectId
|
|
56
|
+
? [
|
|
57
|
+
`coauthor research status ${projectId} --json`,
|
|
58
|
+
`coauthor workflow resume ${projectId} --target draft --wait --json`,
|
|
59
|
+
`coauthor workflow rewind ${projectId} --target research --json`,
|
|
60
|
+
]
|
|
61
|
+
: [
|
|
62
|
+
'coauthor research status <project-id> --json',
|
|
63
|
+
'coauthor workflow resume <project-id> --target draft --wait --json',
|
|
64
|
+
'coauthor workflow rewind <project-id> --target research --json',
|
|
65
|
+
];
|
|
66
|
+
return {
|
|
67
|
+
ok: false,
|
|
68
|
+
status: 'blocked_by_research',
|
|
69
|
+
message: `${message}\nResearch is still marked running. Check status, resume, or rewind the research stage before generating a draft.`,
|
|
70
|
+
recovery_commands: recoveryCommands,
|
|
71
|
+
exitCode: 2,
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
function resolveProjectIdFromArgv(argv) {
|
|
75
|
+
const projectFlagIndex = argv.indexOf('--project');
|
|
76
|
+
if (projectFlagIndex >= 0 && argv[projectFlagIndex + 1])
|
|
77
|
+
return argv[projectFlagIndex + 1];
|
|
78
|
+
const commandWords = new Set([
|
|
79
|
+
'auth',
|
|
80
|
+
'login',
|
|
81
|
+
'status',
|
|
82
|
+
'logout',
|
|
83
|
+
'project',
|
|
84
|
+
'create',
|
|
85
|
+
'list',
|
|
86
|
+
'show',
|
|
87
|
+
'workspace',
|
|
88
|
+
'chat',
|
|
89
|
+
'contract',
|
|
90
|
+
'outline',
|
|
91
|
+
'research-plan',
|
|
92
|
+
'research',
|
|
93
|
+
'run',
|
|
94
|
+
'draft',
|
|
95
|
+
'generate',
|
|
96
|
+
'get',
|
|
97
|
+
'save',
|
|
98
|
+
'workflow',
|
|
99
|
+
'advance',
|
|
100
|
+
'rewind',
|
|
101
|
+
'approve',
|
|
102
|
+
'resume',
|
|
103
|
+
'image',
|
|
104
|
+
'thread',
|
|
105
|
+
'publish',
|
|
106
|
+
'export',
|
|
107
|
+
'operation',
|
|
108
|
+
'credits',
|
|
109
|
+
'skills',
|
|
110
|
+
]);
|
|
111
|
+
return argv.find((arg) => !arg.startsWith('-') && !commandWords.has(arg));
|
|
112
|
+
}
|
|
48
113
|
function extractErrorMessage(body) {
|
|
49
114
|
if (!body || typeof body !== 'object' || Array.isArray(body) || !('error' in body))
|
|
50
115
|
return null;
|
package/dist/parser.js
CHANGED
|
@@ -100,6 +100,8 @@ function commandLength(positionals) {
|
|
|
100
100
|
return second && ['create', 'list', 'show'].includes(second) ? 2 : 1;
|
|
101
101
|
if (first === 'workspace')
|
|
102
102
|
return second === 'show' ? 2 : 1;
|
|
103
|
+
if (first === 'chat')
|
|
104
|
+
return second && ['show', 'list'].includes(second) ? 2 : 1;
|
|
103
105
|
if (first === 'skills')
|
|
104
106
|
return second && ['list', 'install'].includes(second) ? 2 : 1;
|
|
105
107
|
if (first === 'workflow')
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clickminded/coauthor-cli",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.9",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"bin": {
|
|
6
6
|
"coauthor": "dist/index.js",
|
|
@@ -19,11 +19,13 @@
|
|
|
19
19
|
},
|
|
20
20
|
"files": [
|
|
21
21
|
"dist",
|
|
22
|
+
"scripts",
|
|
22
23
|
"skills",
|
|
23
24
|
"README.md"
|
|
24
25
|
],
|
|
25
26
|
"scripts": {
|
|
26
27
|
"build": "tsc",
|
|
28
|
+
"postinstall": "node scripts/postinstall.mjs",
|
|
27
29
|
"test": "node --import tsx --test test/*.test.ts",
|
|
28
30
|
"typecheck": "tsc --noEmit"
|
|
29
31
|
},
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto'
|
|
2
|
+
import { mkdir, readFile, writeFile } from 'node:fs/promises'
|
|
3
|
+
import { dirname, join } from 'node:path'
|
|
4
|
+
import { fileURLToPath } from 'node:url'
|
|
5
|
+
import { homedir } from 'node:os'
|
|
6
|
+
|
|
7
|
+
const packageRoot = fileURLToPath(new URL('..', import.meta.url))
|
|
8
|
+
const registryPath = join(homedir(), '.config', 'coauthor', 'managed-skills.json')
|
|
9
|
+
|
|
10
|
+
async function main() {
|
|
11
|
+
const registry = await readRegistry()
|
|
12
|
+
if (registry.skills.length === 0) return
|
|
13
|
+
|
|
14
|
+
let changed = false
|
|
15
|
+
const nextSkills = []
|
|
16
|
+
for (const skill of registry.skills) {
|
|
17
|
+
const templatePath = resolveTemplatePath(skill.template)
|
|
18
|
+
if (!templatePath) {
|
|
19
|
+
nextSkills.push(skill)
|
|
20
|
+
continue
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
const template = await readFile(templatePath, 'utf8').catch(() => null)
|
|
24
|
+
if (template === null) {
|
|
25
|
+
nextSkills.push(skill)
|
|
26
|
+
continue
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
const current = await readFile(skill.path, 'utf8').catch((error) => {
|
|
30
|
+
return error && error.code === 'ENOENT' ? '' : null
|
|
31
|
+
})
|
|
32
|
+
if (current === null) {
|
|
33
|
+
nextSkills.push(skill)
|
|
34
|
+
continue
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const currentHash = sha256(current)
|
|
38
|
+
const nextHash = sha256(template)
|
|
39
|
+
const safeToUpdate = current === '' || currentHash === skill.templateHash || currentHash === nextHash
|
|
40
|
+
if (!safeToUpdate) {
|
|
41
|
+
nextSkills.push(skill)
|
|
42
|
+
continue
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
if (currentHash !== nextHash) {
|
|
46
|
+
await mkdir(dirname(skill.path), { recursive: true })
|
|
47
|
+
await writeFile(skill.path, template, { mode: 0o644 })
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
nextSkills.push({
|
|
51
|
+
...skill,
|
|
52
|
+
templateHash: nextHash,
|
|
53
|
+
updatedAt: new Date().toISOString(),
|
|
54
|
+
})
|
|
55
|
+
changed = true
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
if (changed) {
|
|
59
|
+
await mkdir(dirname(registryPath), { recursive: true })
|
|
60
|
+
await writeFile(registryPath, `${JSON.stringify({ version: 1, skills: nextSkills }, null, 2)}\n`, { mode: 0o644 })
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
async function readRegistry() {
|
|
65
|
+
try {
|
|
66
|
+
const raw = await readFile(registryPath, 'utf8')
|
|
67
|
+
const parsed = JSON.parse(raw)
|
|
68
|
+
if (parsed?.version !== 1 || !Array.isArray(parsed.skills)) return { version: 1, skills: [] }
|
|
69
|
+
return {
|
|
70
|
+
version: 1,
|
|
71
|
+
skills: parsed.skills.filter((skill) => {
|
|
72
|
+
return skill
|
|
73
|
+
&& typeof skill.skill === 'string'
|
|
74
|
+
&& typeof skill.path === 'string'
|
|
75
|
+
&& typeof skill.template === 'string'
|
|
76
|
+
&& typeof skill.templateHash === 'string'
|
|
77
|
+
}),
|
|
78
|
+
}
|
|
79
|
+
} catch (error) {
|
|
80
|
+
if (error && error.code === 'ENOENT') return { version: 1, skills: [] }
|
|
81
|
+
throw error
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function resolveTemplatePath(template) {
|
|
86
|
+
if (!template.startsWith('../skills/')) return null
|
|
87
|
+
return join(packageRoot, template.replace(/^\.\.\//, ''))
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function sha256(value) {
|
|
91
|
+
return createHash('sha256').update(value).digest('hex')
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
main().catch((error) => {
|
|
95
|
+
console.warn(`[coauthor] skipped managed skill auto-update: ${error instanceof Error ? error.message : String(error)}`)
|
|
96
|
+
})
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: coauthor
|
|
3
|
+
description: Use the CoAuthor Agent CLI for project/workflow operations instead of browser routes, curl, or direct database access. Applies when inspecting or advancing CoAuthor projects, operations, exports, publishing, tokens, or workflow status.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
This skill guides agent use of the CoAuthor CLI.
|
|
7
|
+
|
|
8
|
+
## CLI First
|
|
9
|
+
|
|
10
|
+
- Prefer `coauthor` CLI commands for CoAuthor project and workflow work.
|
|
11
|
+
- Do not drive browser routes, hand-written `curl`, or direct database edits when a CLI command covers the task.
|
|
12
|
+
- Use the configured production base URL by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
|
|
13
|
+
- For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000`.
|
|
14
|
+
- Use `--json` for machine-readable output and parse fields from that output.
|
|
15
|
+
- Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
|
|
16
|
+
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
|
+
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
|
+
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
20
|
+
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
21
|
+
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
22
|
+
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
|
23
|
+
|
|
24
|
+
## Safety
|
|
25
|
+
|
|
26
|
+
- Never print access tokens, publish tokens, service-role keys, cookies, or authorization headers.
|
|
27
|
+
- Never ask the user to paste Anthropic, OpenAI, or Gemini provider API keys into chat or the terminal; key entry belongs in CoAuthor AI settings.
|
|
28
|
+
- Pass tokens through environment variables or secret-backed CLI options only; do not paste them into prompts, logs, or shell history.
|
|
29
|
+
- Treat publish/export operations as live side effects.
|
|
30
|
+
- Require explicit user intent before live publish/export.
|
|
31
|
+
- Include `--yes` only when the user has clearly approved the live publish/export action.
|
|
32
|
+
|
|
33
|
+
## Workflow
|
|
34
|
+
|
|
35
|
+
1. Identify the project, operation, or export target.
|
|
36
|
+
2. Run the relevant `coauthor` command with `--json`.
|
|
37
|
+
3. Add `--wait` when starting or advancing asynchronous work.
|
|
38
|
+
4. If anything is uncertain, query workflow/research/draft status and report the current state.
|
|
39
|
+
5. For live publish/export, confirm explicit user intent, then run with `--yes`.
|
|
40
|
+
|
|
41
|
+
## Chat Transcript
|
|
42
|
+
|
|
43
|
+
Use `coauthor chat show <project-id> --json` to retrieve the workspace chat transcript, especially after long chat responses that may be truncated in terminal capture.
|
|
44
|
+
|
|
45
|
+
When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
|
|
46
|
+
|
|
47
|
+
## Draft Export
|
|
48
|
+
|
|
49
|
+
Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
|
|
50
|
+
|
|
51
|
+
Use `coauthor draft get <project-id> --format html --json` when the user needs HTML with resolved image tags.
|
|
52
|
+
|
|
53
|
+
Use `coauthor draft get <project-id> --format text --json` when the user needs plain text with image URL references.
|
|
54
|
+
|
|
55
|
+
Use `coauthor draft get <project-id> --format json --json` or omit `--format` when the user needs the raw editor document JSON.
|
package/skills/claude/SKILL.md
CHANGED
|
@@ -15,8 +15,11 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
15
15
|
- Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
|
|
16
16
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
17
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
|
+
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
18
20
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
19
21
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
22
|
+
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
|
20
23
|
|
|
21
24
|
## Safety
|
|
22
25
|
|
|
@@ -32,9 +35,15 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
32
35
|
1. Identify the project, operation, or export target.
|
|
33
36
|
2. Run the relevant `coauthor` command with `--json`.
|
|
34
37
|
3. Add `--wait` when starting or advancing asynchronous work.
|
|
35
|
-
4. If anything is uncertain, query
|
|
38
|
+
4. If anything is uncertain, query workflow/research/draft status and report the current state.
|
|
36
39
|
5. For live publish/export, confirm explicit user intent, then run with `--yes`.
|
|
37
40
|
|
|
41
|
+
## Chat Transcript
|
|
42
|
+
|
|
43
|
+
Use `coauthor chat show <project-id> --json` to retrieve the workspace chat transcript, especially after long chat responses that may be truncated in terminal capture.
|
|
44
|
+
|
|
45
|
+
When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
|
|
46
|
+
|
|
38
47
|
## Draft Export
|
|
39
48
|
|
|
40
49
|
Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
|
package/skills/codex/SKILL.md
CHANGED
|
@@ -15,8 +15,11 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
15
15
|
- Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
|
|
16
16
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
17
17
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
18
|
+
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
|
+
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
18
20
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
19
21
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
22
|
+
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
|
20
23
|
|
|
21
24
|
## Safety
|
|
22
25
|
|
|
@@ -32,9 +35,15 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
32
35
|
1. Identify the project, operation, or export target.
|
|
33
36
|
2. Run the relevant `coauthor` command with `--json`.
|
|
34
37
|
3. Add `--wait` when starting or advancing asynchronous work.
|
|
35
|
-
4. If anything is uncertain, query
|
|
38
|
+
4. If anything is uncertain, query workflow/research/draft status and report the current state.
|
|
36
39
|
5. For live publish/export, confirm explicit user intent, then run with `--yes`.
|
|
37
40
|
|
|
41
|
+
## Chat Transcript
|
|
42
|
+
|
|
43
|
+
Use `coauthor chat show <project-id> --json` to retrieve the workspace chat transcript, especially after long chat responses that may be truncated in terminal capture.
|
|
44
|
+
|
|
45
|
+
When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
|
|
46
|
+
|
|
38
47
|
## Draft Export
|
|
39
48
|
|
|
40
49
|
Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
|
|
@@ -12,8 +12,11 @@ alwaysApply: true
|
|
|
12
12
|
- Use `--wait` when starting asynchronous work and the user expects a completed result.
|
|
13
13
|
- Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` for a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
|
|
14
14
|
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
15
|
+
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
16
|
+
- If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
|
|
15
17
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
16
18
|
- After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
|
|
19
|
+
- `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
|
|
17
20
|
- Never print tokens, service-role keys, cookies, or authorization headers.
|
|
18
21
|
- Never ask the user to paste Anthropic, OpenAI, or Gemini provider API keys into chat or the terminal; key entry belongs in CoAuthor AI settings.
|
|
19
22
|
- Pass tokens through environment variables or secret-backed CLI options only.
|
|
@@ -23,6 +26,8 @@ alwaysApply: true
|
|
|
23
26
|
|
|
24
27
|
## Draft Export
|
|
25
28
|
|
|
29
|
+
- Use `coauthor chat show <project-id> --json` to retrieve workspace chat transcripts after long chat responses.
|
|
30
|
+
- Treat `coauthor chat <project-id> --stage draft --json` as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable.
|
|
26
31
|
- Use `coauthor draft get <project-id> --format markdown --json` for finished draft Markdown. Generated images resolve into Markdown image URLs when available.
|
|
27
32
|
- Use `coauthor draft get <project-id> --format html --json` for HTML with resolved image tags.
|
|
28
33
|
- Use `coauthor draft get <project-id> --format text --json` for plain text with image URL references.
|