nightralph 0.0.0

package/src/index.ts

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import yargs from 'yargs'
+import { hideBin } from 'yargs/helpers'
+import { select } from '@inquirer/prompts'
+import { setup, checkGhAuth, type TrackerKind } from './setup.js'
+import {
+    scanTickets,
+    dryRun,
+    runWaves,
+} from './orchestrator.js'
+import {
+    findFeatureDirs,
+    resolveIssuesDir,
+} from './resolve.js'
+
+export { findFeatureDirs, resolveIssuesDir }
+
+const scriptDir = dirname(process.argv[1])
+
+yargs(hideBin(process.argv))
+    .scriptName('nightralph')
+    .usage('$0 <command>')
+    .command(
+        'setup',
+        'Install bundled skills and doc templates',
+        y => y.option('claude', {
+            type:'boolean',
+            describe:'Also create .claude/skills/ symlinks',
+            default:false,
+        }),
+        async argv => {
+            const tracker = await select<TrackerKind>({
+                message:'Issue tracker format',
+                choices:[
+                    {
+                        name:'Local Markdown',
+                        value:'local' as const,
+                        description:'Issues as .md files in ' +
+                            '.scratch/',
+                    },
+                    {
+                        name:'GitHub Issues',
+                        value:'github' as const,
+                        description:'Issues via gh CLI',
+                    },
+                ],
+            })
+
+            if (tracker === 'github') {
+                if (!checkGhAuth()) {
+                    console.error(
+                        'GitHub Issues requires the gh CLI, ' +
+                        'authenticated.\n' +
+                        'Install: https://cli.github.com\n' +
+                        'Then run: gh auth login'
+                    )
+                    process.exit(2)
+                }
+            }
+
+            setup({
+                bundledSkillsDir:join(scriptDir, 'skills'),
+                docsTemplatesDir:join(
+                    scriptDir, 'docs-templates'
+                ),
+                projectDir:process.cwd(),
+                claude:argv.claude,
+                tracker,
+            })
+        }
+    )
+    .command(
+        '$0 <provider>',
+        'Execute tickets with the given provider',
+        y => y
+            .positional('provider', {
+                type:'string',
+                describe:'Agent CLI to spawn (e.g. claude, codex)',
+                demandOption:true,
+            })
+            .option('m', {
+                alias:'model',
+                type:'string',
+                describe:'Model passed to the agent',
+            })
+            .option('dir', {
+                type:'string',
+                describe:'Path to the issues directory',
+            })
+            .option('spec', {
+                type:'string',
+                describe:'Path to the spec file',
+            })
+            .option('dry-run', {
+                type:'boolean',
+                describe:'Show wave order without running',
+                default:false,
+            })
+            .option('timeout-secs', {
+                type:'number',
+                describe:'Kill agent after N seconds',
+                default:300,
+            }),
+        async argv => {
+            await runExecute({
+                provider:argv.provider as string,
+                model:argv.model as string|undefined,
+                dir:argv.dir as string|undefined,
+                spec:argv.spec as string|undefined,
+                dryRun:argv.dryRun as boolean|undefined,
+                timeoutSecs:argv.timeoutSecs as
+                    number|undefined,
+            })
+        }
+    )
+    .strict()
+    .demandCommand(1, 'Specify a command or provider')
+    .help()
+    .parse()
+
+async function runExecute (argv:{
+    provider:string
+    model?:string
+    dir?:string
+    spec?:string
+    dryRun?:boolean
+    timeoutSecs?:number
+}):Promise<void> {
+    const { dir, spec } = await resolveIssuesDir(
+        argv.dir, argv.spec
+    )
+
+    if (!existsSync(dir)) {
+        console.error(`Directory not found: ${dir}`)
+        process.exit(2)
+    }
+    if (!existsSync(spec)) {
+        console.error(`Spec file not found: ${spec}`)
+        process.exit(2)
+    }
+
+    const specBody = readFileSync(spec, 'utf8')
+    const tickets = scanTickets(dir)
+
+    if (tickets.length === 0) {
+        console.log('No ticket files found. Exiting.')
+        return
+    }
+
+    console.log(`Found ${tickets.length} tickets`)
+
+    const knownNums = new Set(tickets.map(t => t.num))
+    for (const t of tickets) {
+        const unknown = t.blockers.filter(
+            b => !knownNums.has(b)
+        )
+        if (unknown.length > 0) {
+            console.warn(
+                `${t.filename}: blockers ` +
+                `[${unknown.join(', ')}] ` +
+                'not found in directory'
+            )
+        }
+        t.blockers = t.blockers.filter(
+            b => knownNums.has(b)
+        )
+    }
+
+    if (argv.dryRun) {
+        dryRun(tickets, specBody)
+        return
+    }
+
+    const logsDir = join(dirname(dir), 'logs')
+    const timeoutSecs = argv.timeoutSecs ?? 300
+    await runWaves(
+        tickets, specBody,
+        argv.provider, argv.model ?? null, timeoutSecs,
+        logsDir,
+    )
+}

package/src/orchestrator.ts

@@ -0,0 +1,324 @@
+import { spawn } from 'node:child_process'
+import {
+    createWriteStream,
+    mkdirSync,
+    readFileSync,
+    writeFileSync,
+    readdirSync,
+} from 'node:fs'
+import { join } from 'node:path'
+
+export type Ticket = {
+    num:number
+    slug:string
+    filename:string
+    filepath:string
+    body:string
+    status:string
+    blockers:number[]
+}
+
+export function formatErrorMessage (error:unknown):string {
+    return error instanceof Error ?
+        error.message :
+        String(error)
+}
+
+export const TICKET_RE = /^(\d+)-(.+)\.md$/
+
+export function parseTicketFilename (
+    filename:string
+):{ num:number; slug:string }|null {
+    const m = filename.match(TICKET_RE)
+    if (!m) return null
+    return { num:Number(m[1]), slug:m[2] }
+}
+
+export function parseStatus (body:string):string {
+    const m = body.match(/\*\*Status:\*\*\s*(.+)/i)
+    return m ? m[1].trim().toLowerCase() : ''
+}
+
+export function parseBlockers (body:string):number[] {
+    const m = body.match(/\*\*Blocked by:\*\*\s*(.+)/i)
+    if (!m) return []
+    const text = m[1]
+    if (/none/i.test(text)) return []
+    const nums:number[] = []
+    const re = /(\d+)/g
+    let match
+    while ((match = re.exec(text))) {
+        nums.push(Number(match[1]))
+    }
+    return nums
+}
+
+export function scanTickets (dir:string):Ticket[] {
+    const files = readdirSync(dir)
+        .filter(f => TICKET_RE.test(f))
+        .sort((a, b) => a.localeCompare(
+            b,
+            undefined,
+            { numeric:true, sensitivity:'base' }
+        ))
+
+    return files.map(filename => {
+        const parsed = parseTicketFilename(filename)!
+        const filepath = join(dir, filename)
+        const body = readFileSync(filepath, 'utf8')
+        return {
+            num:parsed.num,
+            slug:parsed.slug,
+            filename,
+            filepath,
+            body,
+            status:parseStatus(body),
+            blockers:parseBlockers(body),
+        }
+    })
+}
+
+export function findReadyTickets (
+    tickets:ReadonlyArray<Ticket>
+):Ticket[] {
+    const doneNums = new Set(
+        tickets
+            .filter(t => t.status !== 'ready-for-agent')
+            .map(t => t.num)
+    )
+    return tickets.filter(t => {
+        if (t.status !== 'ready-for-agent') return false
+        return t.blockers.every(b => doneNums.has(b))
+    })
+}
+
+export function markDone (ticket:Ticket):void {
+    const updated = ticket.body.replace(
+        /\*\*Status:\*\*\s*.+/i,
+        '**Status:** done'
+    )
+    writeFileSync(ticket.filepath, updated)
+    ticket.status = 'done'
+    ticket.body = updated
+}
+
+export function renderPrompt (
+    specBody:string,
+    ticket:Ticket
+):string {
+    return [
+        '---- SPEC CONTEXT ----',
+        specBody,
+        '',
+        '---- TICKET ----',
+        ticket.filename,
+        ticket.body,
+        '',
+        '---- AGENT INSTRUCTIONS ----',
+        'You are an autonomous coding agent. ' +
+            'Implement the ticket.',
+        '',
+    ].join('\n')
+}
+
+export function spawnAgent (opts:{
+    prompt:string
+    agentCmd:string
+    model:string|null
+    timeoutSecs:number
+    logPath:string
+}):Promise<number> {
+    const args:string[] = []
+    if (opts.model) {
+        args.push('--model', opts.model)
+    }
+
+    const logStream = createWriteStream(
+        opts.logPath,
+        { flags:'w' }
+    )
+    const proc = spawn(opts.agentCmd, args, {
+        stdio:['pipe', 'pipe', 'pipe'],
+    })
+
+    proc.stdout.pipe(logStream)
+    proc.stderr.pipe(logStream)
+
+    const timeout = setTimeout(() => {
+        if (!proc.killed) {
+            console.warn(
+                'Agent did not exit in ' +
+                `${opts.timeoutSecs}s; killing.`
+            )
+            proc.kill('SIGKILL')
+        }
+    }, opts.timeoutSecs * 1000)
+
+    proc.stdin.write(opts.prompt)
+    proc.stdin.end()
+
+    return new Promise<number>(resolve => {
+        proc.on('close', code => {
+            clearTimeout(timeout)
+            logStream.end()
+            resolve(code ?? 1)
+        })
+        proc.on('error', err => {
+            clearTimeout(timeout)
+            logStream.end()
+            console.error(
+                'Agent process error:',
+                formatErrorMessage(err)
+            )
+            resolve(1)
+        })
+    })
+}
+
+export function dryRun (
+    tickets:Ticket[],
+    specBody:string
+):void {
+    console.log('\nTickets:')
+    for (const t of tickets) {
+        const blockerStr = t.blockers.length > 0 ?
+            `blocked by [${t.blockers.join(', ')}]` :
+            'no blockers'
+        console.log(
+            `  ${t.filename} ` +
+            `(${t.status}) ${blockerStr}`
+        )
+    }
+
+    console.log('\nSimulated wave order:')
+    const sim = new Map(
+        tickets.map(t => [t.num, t.status])
+    )
+    let wave = 1
+    while (true) {
+        const doneNums = new Set(
+            [...sim.entries()]
+                .filter(([, s]) => s !== 'ready-for-agent')
+                .map(([n]) => n)
+        )
+        const ready = tickets.filter(t => {
+            if (sim.get(t.num) !== 'ready-for-agent') {
+                return false
+            }
+            return t.blockers.every(
+                b => doneNums.has(b)
+            )
+        })
+        if (ready.length === 0) break
+        console.log(
+            `  Wave ${wave}: ` +
+            ready.map(t => t.filename).join(', ')
+        )
+        for (const t of ready) {
+            sim.set(t.num, 'done')
+        }
+        wave++
+    }
+
+    const stuck = tickets.filter(
+        t => sim.get(t.num) === 'ready-for-agent'
+    )
+    if (stuck.length > 0) {
+        console.log(
+            '\nDeadlocked tickets: ' +
+            stuck.map(t => t.filename).join(', ')
+        )
+    }
+
+    const firstReady = findReadyTickets(tickets)
+    if (firstReady.length > 0) {
+        console.log(
+            '\nPrompt for first ready ticket ' +
+            `(${firstReady[0].filename}):\n`
+        )
+        console.log(
+            renderPrompt(specBody, firstReady[0])
+        )
+    }
+}
+
+export async function runWaves (
+    tickets:Ticket[],
+    specBody:string,
+    agentCmd:string,
+    model:string|null,
+    timeoutSecs:number,
+    logsDir:string,
+):Promise<void> {
+    mkdirSync(logsDir, { recursive:true })
+
+    let totalCompleted = 0
+    let waveNum = 0
+
+    while (true) {
+        const ready = findReadyTickets(tickets)
+        if (ready.length === 0) break
+
+        waveNum++
+        console.log(
+            `\nWave ${waveNum}: ` +
+            ready.map(t => t.filename).join(', ')
+        )
+
+        const results = await Promise.allSettled(
+            ready.map(async t => {
+                const prompt = renderPrompt(specBody, t)
+                const logPath = join(
+                    logsDir,
+                    t.filename.replace(/\.md$/, '.log')
+                )
+                console.log(`  Starting ${t.filename}`)
+                const code = await spawnAgent({
+                    prompt,
+                    agentCmd,
+                    model,
+                    timeoutSecs,
+                    logPath,
+                })
+                return { ticket:t, exitCode:code }
+            })
+        )
+
+        let waveCompleted = 0
+        for (const r of results) {
+            if (r.status === 'rejected') continue
+            const { ticket, exitCode } = r.value
+            if (exitCode === 0) {
+                markDone(ticket)
+                waveCompleted++
+                totalCompleted++
+                console.log(
+                    `  ${ticket.filename}: done`
+                )
+            } else {
+                console.log(
+                    `  ${ticket.filename}: ` +
+                    `agent exited ${exitCode}`
+                )
+            }
+        }
+
+        if (waveCompleted === 0) {
+            console.log(
+                '\nNo tickets completed this wave. ' +
+                'Stopping.'
+            )
+            break
+        }
+    }
+
+    const remaining = tickets.filter(
+        t => t.status === 'ready-for-agent'
+    )
+    console.log(
+        `\nFinished: ${totalCompleted} completed` +
+        (remaining.length > 0 ?
+            `, ${remaining.length} remaining` :
+            '')
+    )
+}

package/src/resolve.ts

@@ -0,0 +1,73 @@
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { select } from '@inquirer/prompts'
+
+export function findFeatureDirs (cwd:string):{
+    name:string;
+    dir:string;
+    spec:string
+}[] {
+    const scratchDir = join(cwd, '.scratch')
+    if (!existsSync(scratchDir)) return []
+    const entries = readdirSync(
+        scratchDir, { withFileTypes:true }
+    )
+    const results:{ name:string; dir:string; spec:string }[] = []
+    for (const entry of entries) {
+        if (!entry.isDirectory()) continue
+        const issuesDir = join(
+            scratchDir, entry.name, 'issues'
+        )
+        const specFile = join(
+            scratchDir, entry.name, 'spec.md'
+        )
+        if (existsSync(issuesDir)) {
+            results.push({
+                name:entry.name,
+                dir:issuesDir,
+                spec:specFile,
+            })
+        }
+    }
+    return results
+}
+
+export async function resolveIssuesDir (
+    dirFlag:string|undefined,
+    specFlag:string|undefined,
+    cwd:string = process.cwd(),
+):Promise<{ dir:string; spec:string }> {
+    if (dirFlag && specFlag) {
+        return { dir:dirFlag, spec:specFlag }
+    }
+
+    const features = findFeatureDirs(cwd)
+
+    if (features.length === 0) {
+        console.error(
+            'No .scratch/<feature>/issues/ directories ' +
+            'found.\nProvide --dir and --spec explicitly.'
+        )
+        process.exit(2)
+    }
+
+    let chosen:typeof features[0]
+    if (features.length === 1) {
+        chosen = features[0]
+        console.log(`Using feature: ${chosen.name}`)
+    } else {
+        const name = await select({
+            message:'Which feature?',
+            choices:features.map(f => ({
+                name:f.name,
+                value:f.name,
+            })),
+        })
+        chosen = features.find(f => f.name === name)!
+    }
+
+    const dir = dirFlag ?? chosen.dir
+    const spec = specFlag ?? chosen.spec
+
+    return { dir, spec }
+}