nightralph 0.0.2 → 0.0.4

package/src/orchestrator.ts

@@ -1,324 +0,0 @@
-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

@@ -1,73 +0,0 @@
-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 }
-}

package/src/setup.ts

@@ -1,157 +0,0 @@
-import {
-    cpSync,
-    existsSync,
-    mkdirSync,
-    readdirSync,
-    readFileSync,
-    symlinkSync,
-    writeFileSync,
-} from 'node:fs'
-import { join } from 'node:path'
-import { execSync } from 'node:child_process'
-
-export const SKILL_DIRS = [
-    'grill', 'grilling', 'domain-modeling',
-    'to-spec', 'to-tickets', 'tdd',
-] as const
-
-export const DOC_TEMPLATES = [
-    'triage-labels.md',
-    'domain.md',
-] as const
-
-export function checkGhAuth ():boolean {
-    try {
-        execSync('gh auth status', { stdio:'ignore' })
-        return true
-    } catch {
-        return false
-    }
-}
-
-export type TrackerKind = 'github'|'local'
-
-export type SetupOpts = {
-    bundledSkillsDir:string
-    docsTemplatesDir:string
-    projectDir:string
-    claude?:boolean
-    tracker:TrackerKind
-}
-
-const TRACKER_TEMPLATES:Record<TrackerKind, string> = {
-    local:'issue-tracker.md',
-    github:'issue-tracker-github.md',
-}
-
-export function setup (opts:SetupOpts):void {
-    const {
-        bundledSkillsDir,
-        docsTemplatesDir,
-        projectDir,
-        claude,
-        tracker,
-    } = opts
-    const agentsSkillsDir = join(
-        projectDir, '.agents', 'skills'
-    )
-
-    const upstream = JSON.parse(
-        readFileSync(
-            join(bundledSkillsDir, 'upstream.json'),
-            'utf8'
-        )
-    ) as { repo:string; commit:string }
-
-    console.log('Installing skills to .agents/skills/\n')
-
-    for (const skill of SKILL_DIRS) {
-        const src = join(bundledSkillsDir, skill)
-        const dest = join(agentsSkillsDir, skill)
-        mkdirSync(dest, { recursive:true })
-        cpSync(src, dest, { recursive:true })
-        const files = readdirSync(src)
-        console.log(
-            `  ${skill}/ (${files.join(', ')})`
-        )
-    }
-
-    if (claude) {
-        const claudeSkillsDir = join(
-            projectDir, '.claude', 'skills'
-        )
-        mkdirSync(claudeSkillsDir, { recursive:true })
-
-        for (const skill of SKILL_DIRS) {
-            const linkPath = join(claudeSkillsDir, skill)
-            const target = join(
-                '..', '..', '.agents', 'skills', skill
-            )
-            if (existsSync(linkPath)) continue
-            symlinkSync(target, linkPath)
-        }
-
-        console.log(
-            '\nCreated symlinks in .claude/skills/'
-        )
-    }
-
-    const docsAgentsDir = join(
-        projectDir, 'docs', 'agents'
-    )
-    mkdirSync(docsAgentsDir, { recursive:true })
-
-    console.log('')
-    for (const tmpl of DOC_TEMPLATES) {
-        const dest = join(docsAgentsDir, tmpl)
-        if (existsSync(dest)) {
-            console.log(
-                `  docs/agents/${tmpl} (already exists)`
-            )
-            continue
-        }
-        const src = join(docsTemplatesDir, tmpl)
-        writeFileSync(dest, readFileSync(src, 'utf8'))
-        console.log(`  docs/agents/${tmpl} (created)`)
-    }
-
-    const trackerSrc = join(
-        docsTemplatesDir, TRACKER_TEMPLATES[tracker]
-    )
-    const trackerDest = join(docsAgentsDir, 'issue-tracker.md')
-    writeFileSync(trackerDest, readFileSync(trackerSrc, 'utf8'))
-    console.log(
-        `  docs/agents/issue-tracker.md (${tracker})`
-    )
-
-    const trackerLine = tracker === 'github' ?
-        'Issues are tracked via GitHub Issues using the `gh` ' +
-        'CLI.' :
-        'Issues are tracked as local markdown files under ' +
-        '`.scratch/`.'
-
-    const agentsMd = [
-        '## Agent skills',
-        '',
-        '### Issue tracker',
-        '',
-        `${trackerLine} See \`docs/agents/issue-tracker.md\`.`,
-        '',
-        '### Triage labels',
-        '',
-        'Default label vocabulary. See ' +
-        '`docs/agents/triage-labels.md`.',
-        '',
-        '### Domain docs',
-        '',
-        'Single-context layout. See `docs/agents/domain.md`.',
-        '',
-    ].join('\n')
-
-    writeFileSync(join(projectDir, 'AGENTS.md'), agentsMd)
-    console.log('\n  AGENTS.md (updated)')
-
-    console.log(
-        `\nSource: ${upstream.repo} @ ${upstream.commit}`
-    )
-}

package/src/skills/domain-modeling/ADR-FORMAT.md

@@ -1,47 +0,0 @@
-# ADR Format
-
-ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
-
-Create the `docs/adr/` directory lazily: only when the first ADR is needed.
-
-## Template
-
-```md
-# {Short title of the decision}
-
-{1-3 sentences: what's the context, what did we decide, and why.}
-```
-
-That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why*, not in filling out sections.
-
-## Optional sections
-
-Only include these when they add genuine value. Most ADRs won't need them.
-
-- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful when decisions are revisited
-- **Considered Options**: only when the rejected alternatives are worth remembering
-- **Consequences**: only when non-obvious downstream effects need to be called out
-
-## Numbering
-
-Scan `docs/adr/` for the highest existing number and increment by one.
-
-## When to offer an ADR
-
-All three of these must be true:
-
-1. **Hard to reverse**: the cost of changing your mind later is meaningful
-2. **Surprising without context**: a future reader will look at the code and wonder "why on earth did they do it this way?"
-3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
-
-If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
-
-### What qualifies
-
-- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
-- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
-- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library: just the ones that would take a quarter to swap out.
-- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
-- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
-- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
-- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it; otherwise someone will suggest GraphQL again in six months.

package/src/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -1,60 +0,0 @@
-# CONTEXT.md Format
-
-## Structure
-
-```md
-# {Context Name}
-
-{One or two sentence description of what this context is and why it exists.}
-
-## Language
-
-**Order**:
-{A one or two sentence description of the term}
-_Avoid_: Purchase, transaction
-
-**Invoice**:
-A request for payment sent to a customer after delivery.
-_Avoid_: Bill, payment request
-
-**Customer**:
-A person or organization that places orders.
-_Avoid_: Client, buyer, account
-```
-
-## Rules
-
-- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
-- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
-- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
-- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
-
-## Single vs multi-context repos
-
-**Single context (most repos):** One `CONTEXT.md` at the repo root.
-
-**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
-
-```md
-# Context Map
-
-## Contexts
-
-- [Ordering](./src/ordering/CONTEXT.md): receives and tracks customer orders
-- [Billing](./src/billing/CONTEXT.md): generates invoices and processes payments
-- [Fulfillment](./src/fulfillment/CONTEXT.md): manages warehouse picking and shipping
-
-## Relationships
-
-- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
-- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
-- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
-```
-
-The skill infers which structure applies:
-
-- If `CONTEXT-MAP.md` exists, read it to find contexts
-- If only a root `CONTEXT.md` exists, single context
-- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
-
-When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.