Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ Title convention — Conventional Commits, in English:
- [ ] Tests pass locally
- [ ] Lint clean (`npm run lint`)
- [ ] Typecheck clean (`npm run typecheck`)
- [ ] Cookbooks synchronized (`npm run docs:check-cookbook`)
- [ ] Secret scan clean (`npm run secret-scan`)
- [ ] No new dependencies without justification
- [ ] No secrets or credentials committed
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -359,3 +359,5 @@ jobs:
run: npm run docs:lint
- name: Changelog structure
run: npm run docs:check-changelog
- name: Cookbook parity
run: npm run docs:check-cookbook
2 changes: 1 addition & 1 deletion AGENTS.global.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- pantheon:generated:begin — Pantheon-managed region; regenerated on install/upgrade, never edit inside -->
<!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->
<!-- Source of truth: src/instructions/*.instructions.md + the static sections in this script. -->
<!-- pantheon:agents-md v2 artifact=global generated-at=2026-11-18T07:45:35-03:00 sha=00e0d08 -->
<!-- pantheon:agents-md v2 artifact=global generated-at=2026-11-19T20:27:31-03:00 sha=5a66b0e -->

# Pantheon Agent System — OpenCode

Expand Down
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- pantheon:generated:begin — Pantheon-managed region; regenerated on install/upgrade, never edit inside -->
<!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->
<!-- Source of truth: project sections in scripts/build-agents-md.mjs. -->
<!-- pantheon:agents-md v2 artifact=project generated-at=2026-11-18T07:45:35-03:00 sha=00e0d08 -->
<!-- pantheon:agents-md v2 artifact=project generated-at=2026-11-19T20:27:31-03:00 sha=5a66b0e -->

# Pantheon — Repository Setup

Expand Down Expand Up @@ -32,5 +32,5 @@ Validate global installation AS A REAL USER in the sandbox `~/pantheon-sandbox/`
- Stronger gates (auth, security, data-integrity, coverage) are canonical in the global `Test Economy` section
- Async/await on all I/O
- Type hints on all functions
- PRs always update the README: document new features, behaviors, env vars, and commands before opening.
- PRs update README + Cookbooks: document features, env vars, commands (`npm run docs:check-cookbook`).
<!-- pantheon:generated:end — user content outside this region is preserved verbatim -->
213 changes: 139 additions & 74 deletions docs/guides/cookbook.md

Large diffs are not rendered by default.

219 changes: 142 additions & 77 deletions docs/pt-BR/guides/cookbook.md

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@
"docs:lint": "node scripts/docs-link-check.mjs",
"docs:media": "node scripts/docs-media.mjs",
"docs:check-changelog": "node scripts/docs-check-changelog.mjs",
"docs:check-cookbook": "node scripts/docs-check-cookbook.mjs",
"typecheck": "tsc --noEmit",
"audit": "npm audit --audit-level=critical",
"secret-scan": "node scripts/secret-scan.mjs",
Expand Down
2 changes: 1 addition & 1 deletion scripts/build-agents-md.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ Validate global installation AS A REAL USER in the sandbox \`~/pantheon-sandbox/
- Stronger gates (auth, security, data-integrity, coverage) are canonical in the global \`Test Economy\` section
- Async/await on all I/O
- Type hints on all functions
- PRs always update the README: document new features, behaviors, env vars, and commands before opening.
- PRs update README + Cookbooks: document features, env vars, commands (\`npm run docs:check-cookbook\`).
`

const INSTRUCTIONS_PREAMBLE = `---
Expand Down
158 changes: 158 additions & 0 deletions scripts/docs-check-cookbook.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
#!/usr/bin/env node
/**
* docs-check-cookbook.mjs — enforce parity between Pantheon's shipped
* commands, TUI surfaces, core native workflows, package minor version,
* and both Practical Cookbooks (docs/guides/cookbook.md & docs/pt-BR/guides/cookbook.md).
*
* Exits 1 when either cookbook drifts behind code or version bumps.
*/

import { existsSync, readFileSync } from 'node:fs'
import { dirname, join, resolve } from 'node:path'
import { fileURLToPath, pathToFileURL } from 'node:url'

const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')

export const REQUIRED_CORE_MARKERS = [
'ast_search',
'ast_rewrite',
'hashline_edit',
'pantheon_step_ledger',
'pantheon_worktree',
'pantheon_review_verdict',
'detect_stack',
'pantheon_agent_forge',
'memory_search',
'APPROVE',
'APPROVE_WITH_NOTES',
'BLOCK',
]

export const STALE_COOKBOOK_PATTERNS = [
{
pattern: /\bPASS_WITH_NOTES\b/,
reason: 'obsolete verdict label PASS_WITH_NOTES (use APPROVE / APPROVE_WITH_NOTES / BLOCK)',
},
]

function extractServerCommands(pluginSource) {
const blockMatch = /const CANONICAL_SLASH_COMMANDS[^=]*=\s*\[([\s\S]*?)\n\]/.exec(pluginSource)
if (!blockMatch) return []
return [...blockMatch[1].matchAll(/\bname:\s*['"]([a-z0-9-]+)['"]/g)].map((m) => m[1])
}

function extractTuiCommands(tuiIndexSource) {
const start = tuiIndexSource.indexOf('function PantheonSettingsCommandLayer')
if (start === -1) return []
const slice = tuiIndexSource.slice(start, start + 2500)
return [...slice.matchAll(/slash:\s*\{\s*name:\s*['"]([a-z0-9-]+)['"]/g)].map((m) => m[1])
}

function expectedMinorTag(version) {
const match = /^(\d+)\.(\d+)\./.exec(String(version ?? '').trim())
return match ? `v${match[1]}.${match[2]}` : null
}

function escapeRegExp(value) {
return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
}

function checkCookbookDocument(label, content, { expectedTag, commands, coreMarkers }) {
const findings = []
if (!expectedTag) {
findings.push(`${label}: could not determine package.json major.minor version`)
} else {
const tagMarker = `<!-- pantheon:cookbook-version ${expectedTag} -->`
if (!content.includes(tagMarker)) {
findings.push(
`${label}: missing current minor sync marker '${tagMarker}' — review and update recipes for ${expectedTag}`,
)
}
}

for (const cmd of commands) {
const cmdRe = new RegExp(`/${escapeRegExp(cmd)}(?![a-z0-9-])`)
if (!cmdRe.test(content)) {
findings.push(`${label}: missing documented command /${cmd}`)
}
}

for (const marker of coreMarkers) {
const markerRe = new RegExp(`\\b${escapeRegExp(marker)}\\b`)
if (!markerRe.test(content)) {
findings.push(`${label}: missing v2.2+ core workflow/tool marker '${marker}'`)
}
}

for (const rule of STALE_COOKBOOK_PATTERNS) {
if (rule.pattern.test(content)) {
findings.push(`${label}: contains ${rule.reason}`)
}
}

return findings
}

export function checkCookbookParity(rootDir = ROOT) {
const findings = []
const pkgPath = join(rootDir, 'package.json')
const pluginPath = join(rootDir, 'src', 'plugin.ts')
const tuiPath = join(rootDir, 'src', 'plugins', 'tui', 'src', 'index.tsx')
const enPath = join(rootDir, 'docs', 'guides', 'cookbook.md')
const ptPath = join(rootDir, 'docs', 'pt-BR', 'guides', 'cookbook.md')

if (!existsSync(pkgPath)) {
return { findings: ['package.json missing'], discoveredCommands: [], expectedTag: null }
}
const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
const expectedTag = expectedMinorTag(pkg.version)

const serverCommands = existsSync(pluginPath)
? extractServerCommands(readFileSync(pluginPath, 'utf8'))
: []
const tuiCommands = existsSync(tuiPath) ? extractTuiCommands(readFileSync(tuiPath, 'utf8')) : []
const discoveredCommands = [...new Set([...serverCommands, ...tuiCommands])]

if (discoveredCommands.length === 0) {
findings.push(
'Unable to discover any canonical slash commands in src/plugin.ts or TUI index.tsx',
)
}

for (const [label, filePath] of [
['docs/guides/cookbook.md', enPath],
['docs/pt-BR/guides/cookbook.md', ptPath],
]) {
if (!existsSync(filePath)) {
findings.push(`${label}: file missing`)
continue
}
const content = readFileSync(filePath, 'utf8')
findings.push(
...checkCookbookDocument(label, content, {
expectedTag,
commands: discoveredCommands,
coreMarkers: REQUIRED_CORE_MARKERS,
}),
)
}

return { findings, discoveredCommands, expectedTag }
}

const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href

if (isDirectRun) {
const { findings, discoveredCommands, expectedTag } = checkCookbookParity(ROOT)
if (findings.length > 0) {
console.error(`docs:check-cookbook failed (${findings.length} finding(s)):`)
for (const finding of findings) {
console.error(` - ${finding}`)
}
process.exitCode = 1
} else {
console.log(
`docs:check-cookbook OK — EN + pt-BR cookbooks match ${expectedTag} (${discoveredCommands.length} commands, ${REQUIRED_CORE_MARKERS.length} core markers).`,
)
}
}
3 changes: 3 additions & 0 deletions scripts/release-gates.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -541,6 +541,9 @@ function metadataGate(options) {
run('version-manifests', 'node', ['scripts/version-check.mjs']),
run('node-engine-policy', 'node', ['scripts/validate-node-engine-policy.mjs']),
]
if (!options.recovery) {
checks.push(run('cookbook-parity', 'node', ['scripts/docs-check-cookbook.mjs']))
}
return {
checks,
details: {
Expand Down
108 changes: 108 additions & 0 deletions tests/docs-cookbook.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
import assert from 'node:assert/strict'
import { execFileSync } from 'node:child_process'
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, test } from 'node:test'
import { fileURLToPath } from 'node:url'

const ROOT = fileURLToPath(new URL('..', import.meta.url))
const SCRIPT = join(ROOT, 'scripts/docs-check-cookbook.mjs')
const tempDirs = []

function makeTempRepo({
version = '2.2.0',
serverCommands = ['pantheon', 'pantheon-forge'],
tuiCommands = ['pantheon-cockpit'],
cookbookEn = '',
cookbookPt = '',
} = {}) {
const dir = mkdtempSync(join(tmpdir(), 'pantheon-cookbook-check-'))
tempDirs.push(dir)
mkdirSync(join(dir, 'src/plugins/tui/src'), { recursive: true })
mkdirSync(join(dir, 'docs/guides'), { recursive: true })
mkdirSync(join(dir, 'docs/pt-BR/guides'), { recursive: true })

writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'pantheon-opencode', version }))
writeFileSync(
join(dir, 'src/plugin.ts'),
`const CANONICAL_SLASH_COMMANDS = [\n${serverCommands
.map((name) => ` { name: '${name}', description: 'desc' },`)
.join('\n')}\n]\n`,
)
writeFileSync(
join(dir, 'src/plugins/tui/src/index.tsx'),
`function PantheonSettingsCommandLayer() {\n const cmds = [\n${tuiCommands
.map((name) => ` { slash: { name: '${name}' } },`)
.join('\n')}\n ]\n}\n`,
)
writeFileSync(join(dir, 'docs/guides/cookbook.md'), cookbookEn)
writeFileSync(join(dir, 'docs/pt-BR/guides/cookbook.md'), cookbookPt)
return dir
}

const VALID_BODY = `
<!-- pantheon:cookbook-version v2.2 -->
Uses /pantheon, /pantheon-forge, /pantheon-cockpit,
ast_search, ast_rewrite, hashline_edit, pantheon_step_ledger,
pantheon_worktree, pantheon_review_verdict, detect_stack,
pantheon_agent_forge, memory_search, APPROVE, APPROVE_WITH_NOTES, BLOCK.
`

afterEach(() => {
while (tempDirs.length > 0) {
rmSync(tempDirs.pop(), { recursive: true, force: true })
}
})

describe('scripts/docs-check-cookbook.mjs', () => {
test('passes on synchronized EN and pt-BR cookbooks', async () => {
const { checkCookbookParity } = await import(SCRIPT)
const dir = makeTempRepo({ cookbookEn: VALID_BODY, cookbookPt: VALID_BODY })
const result = checkCookbookParity(dir)
assert.deepEqual(result.findings, [])
assert.deepEqual(result.discoveredCommands.sort(), [
'pantheon',
'pantheon-cockpit',
'pantheon-forge',
])
})

test('fails when package.json minor version advances without cookbook version bump', async () => {
const { checkCookbookParity } = await import(SCRIPT)
const dir = makeTempRepo({
version: '2.3.0',
cookbookEn: VALID_BODY,
cookbookPt: VALID_BODY,
})
const result = checkCookbookParity(dir)
assert.ok(result.findings.some((f) => /cookbook-version v2\.3/.test(f)))
})

test('fails when a new server or TUI slash command is missing from either cookbook', async () => {
const { checkCookbookParity } = await import(SCRIPT)
const dir = makeTempRepo({
serverCommands: ['pantheon', 'pantheon-forge', 'pantheon-new-cmd'],
tuiCommands: ['pantheon-cockpit'],
cookbookEn: `${VALID_BODY}\n/pantheon-new-cmd`,
cookbookPt: VALID_BODY,
})
const result = checkCookbookParity(dir)
assert.ok(result.findings.some((f) => f.includes('pt-BR') && f.includes('/pantheon-new-cmd')))
})

test('fails when obsolete PASS_WITH_NOTES verdict marker appears', async () => {
const { checkCookbookParity } = await import(SCRIPT)
const dir = makeTempRepo({
cookbookEn: `${VALID_BODY}\nVerdict: PASS_WITH_NOTES`,
cookbookPt: VALID_BODY,
})
const result = checkCookbookParity(dir)
assert.ok(result.findings.some((f) => f.includes('PASS_WITH_NOTES')))
})

test('repository cookbooks satisfy full CI parity check', () => {
const output = execFileSync(process.execPath, [SCRIPT], { cwd: ROOT, encoding: 'utf8' })
assert.match(output, /docs:check-cookbook OK/)
})
})
Loading