Something went wrong. Try again.
The
gh equivalent for tangled.org Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293import { GLOBAL_OPTIONS, type Command, type OptionSpec } from './lib/command.ts';import { root } from './commands/root.ts';
// The command reference as Markdown, for the agent skill: generated from the// same tree the parser uses. Every runnable command declares whether it// writes (`writes` on its spec); this generator refuses to run while one// does not, so the classification cannot silently fall behind the commands.
/** What to say, beneath the summary, of a command whose writeness depends on how it is used. */const CAVEATS: Record<string, string> = { 'tangled api': 'Whether it writes depends on the method: queries (GET) read, procedures (POST) write.', 'tangled issue label': 'Without --add or --remove it only shows labels; with them it writes.', 'tangled pr label': 'Without --add or --remove it only shows labels; with them it writes.',};
function flag(name: string, option: OptionSpec): string { const value = option.type === 'boolean' ? '' : ` <${option.placeholder ?? 'string'}>`; return `${option.short ? `-${option.short}, ` : ''}--${name}${value}`;}
function describe(option: OptionSpec): string { return option.multiple ? `${option.description} (repeatable)` : option.description;}
function writesLine(command: Command): string | undefined { if (command.writes === 'network') return '**Writes to the network.** It changes a repository, a knot, or publishes something other people can see.'; if (command.writes === 'local') return "**Writes only on this machine.** It changes local state — sessions, config, git config, the shell's startup file — and nothing on the network."; return undefined;}
export function reference(): string { const network: string[] = []; const local: string[] = []; const lines: string[] = [ '# tangled command reference', '', '<!-- Generated by `node tools/reference.ts` from the command tree. Do not edit by hand. -->', '', '## Which commands write', '', 'Every command reads unless it is listed here.', '', 'These write to the network: they change a repository, a knot or a spindle, or publish something other people can see. An agent should have its user\'s ok before running one, unless the user asked for that exact action:', '', ]; const visit = (path: Command[]) => { const command = path[path.length - 1]!; if (command.hidden) return; if (path.length > 1) { const name = ['tangled', ...path.slice(1).map((each) => each.name)].join(' '); if (command.run && command.writes === undefined) { throw new Error(`reference: ${name} does not say whether it writes — set writes: false, 'local' or 'network' on its spec`); } if (command.run && command.writes === 'network') network.push(`\`${name}\``); if (command.run && command.writes === 'local') local.push(`\`${name}\``); lines.push(`${'#'.repeat(Math.min(path.length + 1, 4))} \`${name}\``, '', `${command.summary}.`, ''); const writes = writesLine(command); if (writes) lines.push(writes, ''); const caveat = CAVEATS[name]; if (caveat) lines.push(caveat, ''); if (command.aliases?.length) lines.push(`Also: ${command.aliases.map((alias) => `\`${alias}\``).join(', ')}.`, ''); if (command.run) { const flags = Object.keys(command.options ?? {}).length ? ' [flags]' : ''; lines.push('```', `${name}${command.args ? ` ${command.args}` : ''}${flags}`, '```', ''); for (const option of Object.entries(command.options ?? {})) lines.push(`- \`${flag(option[0], option[1])}\`: ${describe(option[1]).replace(/\|/g, '\\|')}`); if (Object.keys(command.options ?? {}).length) lines.push(''); if (command.examples?.length) { lines.push('Examples:', ''); for (const example of command.examples) lines.push(`- \`${example.replace(/`/g, '\\`')}\``); lines.push(''); } } } for (const sub of command.subcommands ?? []) visit([...path, sub]); }; visit([root]); lines.push( network.length ? `- ${network.join(', ')}.` : '- (none).', '', 'These write only on this machine — sessions, config, git config, the shell\'s startup file. Nothing on the network changes:', '', local.length ? `- ${local.join(', ')}.` : '- (none).', '', 'And `tangled api` does either, depending on the method: queries (GET) read, procedures (POST) write.', '', 'Every command also takes the global options:', '', ...Object.entries(GLOBAL_OPTIONS).map(([name, option]) => `- \`${flag(name, option)}\`: ${describe(option).replace(/\|/g, '\\|')}`), '', ); return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;}