1
+import { describe, expect, test } from 'bun:test';
2
+import { spawnSync } from 'node:child_process';
3
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
4
+import { tmpdir } from 'node:os';
5
+import { join, resolve } from 'node:path';
6
+import { z } from 'zod';
7
+
8
+const workflowSchema = z.object({
9
+ jobs: z.record(z.string(), z.object({
10
+ defaults: z.object({ run: z.object({ shell: z.string().optional() }) }).optional(),
11
+ steps: z.array(z.object({ name: z.string(), run: z.string().optional(), shell: z.string().optional() })),
12
+ })),
13
+});
14
+const workflows = {
15
+ publish: workflowSchema.parse(Bun.YAML.parse(readFileSync(
16
+ resolve(process.cwd(), '..', '.github/workflows/docs-kb-publish.yml'), 'utf8',
17
+ ))),
18
+ refresh: workflowSchema.parse(Bun.YAML.parse(readFileSync(
19
+ resolve(process.cwd(), '..', '.github/workflows/docs-update-kb.yml'), 'utf8',
20
+ ))),
21
+};
22
+
23
+function runStep(
24
+ name: string, root: string, env: Record<string, string> = {}, job: 'publish' | 'refresh' = 'publish',
25
+) {
26
+ const definition = workflows[job].jobs[job]!;
27
+ const step = definition.steps.find(step => step.name === name);
28
+ const script = step?.run;
29
+ if (!script) throw new Error(`Missing workflow step: ${name}`);
30
+ // Match the Actions runner: implicit bash omits pipefail; explicit bash enables it.
31
+ const shell = step?.shell ?? definition.defaults?.run.shell;
32
+ const shellFlags = shell === 'bash' ? ['--noprofile', '--norc', '-e', '-o', 'pipefail'] : ['-e'];
33
+ return spawnSync('bash', [...shellFlags, '-c', script], {
34
+ cwd: root,
35
+ encoding: 'utf8',
36
+ env: {
37
+ ...process.env,
38
+ PATH: `${join(root, 'bin')}:${process.env.PATH}`,
39
+ FIXTURE_ROOT: root,
40
+ RUNNER_TEMP: root,
41
+ GH_REPO: 'ComposioHQ/composio',
42
+ PUBLISH_BRANCH: job === 'publish' ? 'docs/kb-front-desk-2' : 'docs/auto-update-kb',
43
+ GUIDE_SLUG: 'sdk-example',
44
+ ...env,
45
+ },
46
+ });
47
+}
48
+
49
+function fixture() {
50
+ const root = mkdtempSync(join(tmpdir(), 'kb-publication-'));
51
+ mkdirSync(join(root, 'bin'));
52
+ writeFileSync(join(root, 'calls'), '');
53
+ writeFileSync(join(root, 'sleeps'), '');
54
+ writeFileSync(join(root, 'bin/gh'), `#!/bin/bash
55
+set -euo pipefail
56
+echo called >> "$FIXTURE_ROOT/calls"
57
+if [ "\${FAIL_API:-false}" = true ]; then exit 1; fi
58
+if [[ " $* " == *" --paginate "* ]]; then
59
+ cat "$FIXTURE_ROOT/current.jsonl"
60
+else
61
+ head -n 1 "$FIXTURE_ROOT/current.jsonl"
62
+fi | jq -r "\${@: -1}"
63
+`, { mode: 0o755 });
64
+ writeFileSync(join(root, 'bin/sleep'), `#!/bin/bash
65
+set -euo pipefail
66
+echo slept >> "$FIXTURE_ROOT/sleeps"
67
+if [ -f "$FIXTURE_ROOT/after.jsonl" ]; then
68
+ cp "$FIXTURE_ROOT/after.jsonl" "$FIXTURE_ROOT/current.jsonl"
69
+fi
70
+`, { mode: 0o755 });
71
+ writeFileSync(join(root, 'bin/bun'), `#!/bin/bash
72
+set -euo pipefail
73
+if [ "$2" = verify:kb ]; then
74
+ cat "$FIXTURE_ROOT/report.json"
75
+ exit "\${VERIFY_EXIT:-0}"
76
+fi
77
+`, { mode: 0o755 });
78
+ return root;
79
+}
80
+
81
+const earlierPublication = {
82
+ head: { ref: 'docs/kb-front-desk-1', repo: { full_name: 'ComposioHQ/composio' } },
83
+ html_url: 'https://github.com/ComposioHQ/composio/pull/1',
84
+};
85
+
86
+describe('KB publication workflow', () => {
87
+ test('waits for an earlier publication across pages while allowing the current draft and unrelated PRs', () => {
88
+ const root = fixture();
89
+ try {
90
+ const unrelated = { head: { ref: 'docs/unrelated' }, html_url: 'unrelated' };
91
+ const currentDraft = { head: { ref: 'docs/kb-front-desk-2', repo: { full_name: 'ComposioHQ/composio' } }, html_url: 'current' };
92
+ writeFileSync(join(root, 'current.jsonl'),
93
+ `${JSON.stringify([unrelated, currentDraft])}\n${JSON.stringify([earlierPublication])}\n`);
94
+ writeFileSync(join(root, 'after.jsonl'), `${JSON.stringify([unrelated, currentDraft])}\n`);
95
+
96
+ const result = runStep('Wait for earlier KB publications', root);
97
+
98
+ expect(result.status).toBe(0);
99
+ expect(result.stdout).toContain(earlierPublication.html_url);
100
+ expect(result.stdout).not.toContain('unrelated');
101
+ expect(result.stdout).not.toContain('current');
102
+ expect(readFileSync(join(root, 'calls'), 'utf8').trim().split('\n')).toHaveLength(2);
103
+ expect(readFileSync(join(root, 'sleeps'), 'utf8').trim().split('\n')).toHaveLength(1);
104
+ } finally {
105
+ rmSync(root, { recursive: true, force: true });
106
+ }
107
+ });
108
+
109
+ test.each(['publish', 'refresh'] as const)('%s ignores fork PRs that imitate publication branches', job => {
110
+ const root = fixture();
111
+ try {
112
+ const forkPrs = ['docs/kb-front-desk-hold', 'docs/auto-update-kb'].map(ref => ({
113
+ head: { ref, repo: { full_name: 'outsider/composio' } }, html_url: 'fork-pr',
114
+ }));
115
+ writeFileSync(join(root, 'current.jsonl'), JSON.stringify(forkPrs));
116
+ const result = runStep('Wait for earlier KB publications', root, {}, job);
117
+ expect(result.status).toBe(0);
118
+ expect(result.stdout).not.toContain('fork-pr');
119
+ expect(readFileSync(join(root, 'sleeps'), 'utf8')).toBe('');
120
+ } finally {
121
+ rmSync(root, { recursive: true, force: true });
122
+ }
123
+ });
124
+
125
+ test.each([
126
+ ['publish', 'docs/auto-update-kb'],
127
+ ['refresh', 'docs/kb-front-desk-1'],
128
+ ] as const)('%s waits for the other publication path to merge', (job, ref) => {
129
+ const root = fixture();
130
+ try {
131
+ writeFileSync(join(root, 'current.jsonl'), JSON.stringify([{
132
+ head: { ref, repo: { full_name: 'ComposioHQ/composio' } }, html_url: 'earlier-kb-publication',
133
+ }]));
134
+ writeFileSync(join(root, 'after.jsonl'), '[]');
135
+ const result = runStep('Wait for earlier KB publications', root, {}, job);
136
+ expect(result.status).toBe(0);
137
+ expect(result.stdout).toContain('earlier-kb-publication');
138
+ expect(readFileSync(join(root, 'calls'), 'utf8').trim().split('\n')).toHaveLength(2);
139
+ } finally {
140
+ rmSync(root, { recursive: true, force: true });
141
+ }
142
+ });
143
+
144
+ test('fails with a recovery instruction when an earlier publication stays open', () => {
145
+ const root = fixture();
146
+ try {
147
+ writeFileSync(join(root, 'current.jsonl'), `${JSON.stringify([earlierPublication])}\n`);
148
+
149
+ const result = runStep('Wait for earlier KB publications', root);
150
+
151
+ expect(result.status).toBe(1);
152
+ expect(result.stderr).toContain('Merge or close them, then rerun this workflow.');
153
+ expect(readFileSync(join(root, 'calls'), 'utf8').trim().split('\n')).toHaveLength(60);
154
+ } finally {
155
+ rmSync(root, { recursive: true, force: true });
156
+ }
157
+ });
158
+
159
+ test('stops on an API failure instead of assuming no earlier publication exists', () => {
160
+ const root = fixture();
161
+ try {
162
+ const result = runStep('Wait for earlier KB publications', root, { FAIL_API: 'true' });
163
+
164
+ expect(result.status).toBe(1);
165
+ expect(readFileSync(join(root, 'calls'), 'utf8').trim().split('\n')).toHaveLength(1);
166
+ expect(readFileSync(join(root, 'sleeps'), 'utf8')).toBe('');
167
+ } finally {
168
+ rmSync(root, { recursive: true, force: true });
169
+ }
170
+ });
171
+
172
+ test('blocks support-facing prose even when verification reports it as a warning', () => {
173
+ const root = fixture();
174
+ try {
175
+ writeFileSync(join(root, 'report.json'), JSON.stringify({
176
+ findings: [{ severity: 'warning', kind: 'unedited-support-prose', guideSlug: 'sdk-example' }],
177
+ }));
178
+
179
+ const result = runStep('Regenerate KB pages', root);
180
+
181
+ expect(result.status).toBe(1);
182
+ expect(result.stderr).toContain('Rewrite it for public readers');
183
+ } finally {
184
+ rmSync(root, { recursive: true, force: true });
185
+ }
186
+ });
187
+
188
+ test('allows an approval when only another guide has support-facing prose', () => {
189
+ const root = fixture();
190
+ try {
191
+ writeFileSync(join(root, 'report.json'), JSON.stringify({
192
+ findings: [{ severity: 'warning', kind: 'unedited-support-prose', guideSlug: 'other-guide' }],
193
+ }));
194
+ expect(runStep('Regenerate KB pages', root).status).toBe(0);
195
+ } finally {
196
+ rmSync(root, { recursive: true, force: true });
197
+ }
198
+ });
199
+
200
+ test('allows advisory review cohorts while retaining verification errors', () => {
201
+ const root = fixture();
202
+ try {
203
+ writeFileSync(join(root, 'report.json'), JSON.stringify({
204
+ findings: [{ severity: 'warning', kind: 'review-window-cliff' }],
205
+ }));
206
+ expect(runStep('Regenerate KB pages', root).status).toBe(0);
207
+
208
+ writeFileSync(join(root, 'report.json'), JSON.stringify({
209
+ findings: [{ severity: 'error', kind: 'unknown-tool-slug' }],
210
+ }));
211
+ expect(runStep('Regenerate KB pages', root, { VERIFY_EXIT: '1' }).status).toBe(1);
212
+ } finally {
213
+ rmSync(root, { recursive: true, force: true });
214
+ }
215
+ });
216
+});