ranni-cli 0.0.0-stage → 0.2.3

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# Ranni
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The work frontier agents leave behind. Ranni keeps the living state of in-flight work as
+ordinary Relic records, so any agent, harness or human can
+pick it up. It never runs agents, keeps no queue and stores no status: `ranni status`
+derives the board from Relic, Git and the Git host every time you ask.
+
+Spec: [`.relic/specs/001-work-frontier/index.html`](.relic/specs/001-work-frontier/index.html)
+
+## Requirements
+
+- Relic 2.3.0 or later, with structured search (`relic search --kind <kind> --json`,
+  `formatVersion` 1). Ranni consumes Relic's read model and never parses the corpus.
+- `git`. `gh` is optional: without it (or without auth or network) `status` shows Git evidence
+  only and says what is missing.
+- Bun.
+
+## Install
+
+```bash
+bun add -g ranni-cli
+```
+
+The 0.1 MCP orchestrator was published as `ranni-mcp`; Ranni 2 is published as `ranni-cli`, and the command is `ranni`.
+
+## `ranni init`
+
+```bash
+relic init && relic install   # once, if the project has no Relic yet
+ranni init
+```
+
+Idempotent. It requires an existing `relic.yaml` (it never creates one), adds a `work` record
+kind to `topology.records` only if none is declared (comments and formatting are kept), and
+installs the Ranni skill next to every installed Relic skill (`<dot-dir>/skills/ranni/`).
+Running it again only refreshes the skill and prints what changed.
+
+## `ranni status`
+
+```bash
+ranni status [id...] [--json] [--kind <kind>]
+```
+
+A read-only board grouped by the first label that applies, with the age of the last activity
+and links to related work items (`-> WORK-041 in review`):
+
+1. Waiting on you: the `waiting` frontmatter key is set.
+2. Ready to close: a pull request mentioning it is merged (or, without `gh`, a branch fully merged).
+3. In review: an open pull request, with requested changes, unresolved threads, failing checks or approval.
+4. In flight: branches or commits, no pull request yet.
+5. Not started: no traces.
+
+There is no staleness threshold and no computed blocking; the reader decides.
+
+## The executor contract
+
+Any agent or human leaves traces the board can read:
+
+- the branch name contains the identity, for example `work/WORK-042-push`;
+- commits carry a trailer, `Work: WORK-042`;
+- the pull request title or head branch mentions the identity, or its body carries `Work: WORK-042`;
+- the current frontier section of the work item is rewritten at natural stopping points.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run typecheck
+bun run ranni -- status
+```

package/bin/ranni.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/index.ts'

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "ranni-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.3",
+  "description": "Ranni 2: the work frontier agents leave behind, derived from Relic, Git and the Git host",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/filfp/ranni"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "bin": {
+    "ranni": "bin/ranni.js"
+  },
+  "scripts": {
+    "ranni": "bun run src/index.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "release": "bun run scripts/publish.ts"
+  },
+  "dependencies": {
+    "yaml": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.4.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs'
+import { RanniError } from './errors'
+import { runInit } from './init'
+import type { Io } from './init'
+import { renderHuman } from './render'
+import { run } from './runner'
+import { buildStatus } from './status'
+
+const HELP = `ranni: the work frontier agents leave behind
+
+Usage:
+  ranni init                              Declare the work kind in relic.yaml and install the Ranni skill
+  ranni status [id...] [--json] [--kind <kind>]
+                                          Board derived from Relic, Git and the Git host (default kind: work)
+  ranni --help | --version
+`
+
+
+export async function main(argv: string[], cwd: string, io: Io): Promise<number> {
+  const [cmd, ...rest] = argv
+  try {
+    switch (cmd) {
+      case undefined:
+      case '-h':
+      case '--help':
+      case 'help':
+        io.out(HELP)
+        return cmd === undefined ? 1 : 0
+      case '-V':
+      case '--version': {
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+        io.out(`${pkg.version}\n`)
+        return 0
+      }
+      case 'init': {
+        if (rest.length) throw new RanniError(`ranni init takes no arguments (got "${rest[0]}").`)
+        return runInit(cwd, io)
+      }
+      case 'status': {
+        let json = false
+        let kind = 'work'
+        const ids: string[] = []
+        for (let i = 0; i < rest.length; i++) {
+          const a = rest[i]
+          if (a === '--json') json = true
+          else if (a === '--kind') {
+            const v = rest[++i]
+            if (!v || v.startsWith('-')) throw new RanniError('--kind needs a value.')
+            kind = v
+          } else if (a.startsWith('--kind=')) kind = a.slice('--kind='.length)
+          else if (a.startsWith('-')) throw new RanniError(`Unknown option ${a}.`)
+          else ids.push(a)
+        }
+        const model = await buildStatus(
+          { run, now: new Date(), cwd },
+          { kind, ids },
+        )
+        io.out(json ? JSON.stringify(model, null, 2) + '\n' : renderHuman(model))
+        return 0
+      }
+      default:
+        throw new RanniError(`Unknown command "${cmd}". Try ranni --help.`)
+    }
+  } catch (e) {
+    if (e instanceof RanniError) {
+      io.err(`ranni: ${e.message}\n`)
+      return 1
+    }
+    throw e
+  }
+}

package/src/derive.ts

@@ -0,0 +1,90 @@
+import type { Derived, Evidence, Label, PullRequestEvidence } from './types'
+
+/**
+ * Whether `text` mentions the identity, case-insensitively. The identity must not be
+ * glued to more letters or digits, so WORK-04 is not found inside WORK-042.
+ */
+export function mentions(text: string, id: string): boolean {
+  if (!text || !id) return false
+  const esc = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`(?<![A-Za-z0-9])${esc}(?![A-Za-z0-9])`, 'i').test(text)
+}
+
+/**
+ * Whether `body` declares the identity on a `Work:` line, the same shape as the commit
+ * trailer. Several identities may share one line, separated by commas or spaces. Plain
+ * mentions elsewhere in the body ("depends on WORK-041") do not count.
+ */
+export function declaresWork(body: string, id: string): boolean {
+  if (!body || !id) return false
+  for (const match of body.matchAll(/^[ \t]*Work:[ \t]*(.+)$/gim)) {
+    if (match[1]!.split(/[\s,]+/).some(token => token.toLowerCase() === id.toLowerCase())) return true
+  }
+  return false
+}
+
+export function newest(dates: (string | undefined)[]): string | undefined {
+  let best: string | undefined
+  let bestT = -Infinity
+  for (const d of dates) {
+    if (!d) continue
+    const t = Date.parse(d)
+    if (Number.isNaN(t)) continue
+    if (t > bestT) {
+      bestT = t
+      best = d
+    }
+  }
+  return best
+}
+
+export function lastActivity(e: Evidence): string | undefined {
+  return newest([...e.git.branches.map(b => b.date), ...e.git.commits.map(c => c.date)])
+}
+
+export function isMergedPr(pr: PullRequestEvidence, defaultBranch: string | undefined): boolean {
+  if (pr.state !== 'MERGED') return false
+  // A PR merged into another branch has not landed on the default branch yet.
+  return !defaultBranch || !pr.baseRef || pr.baseRef === defaultBranch
+}
+
+export function openPrs(e: Evidence): PullRequestEvidence[] {
+  return e.pullRequests.filter(p => p.state === 'OPEN')
+}
+
+/**
+ * The first label that applies, as in the spec:
+ * waiting, ready to close, in review, in flight, not started.
+ */
+export function deriveLabel(
+  item: { waiting?: string },
+  e: Evidence,
+  defaultBranch: string | undefined,
+): Label {
+  if (item.waiting !== undefined) return 'waiting'
+  if (e.mergedByGit || e.pullRequests.some(p => isMergedPr(p, defaultBranch))) return 'ready-to-close'
+  if (openPrs(e).length > 0) return 'in-review'
+  if (e.git.branches.length > 0 || e.git.commits.length > 0) return 'in-flight'
+  return 'not-started'
+}
+
+export function derive(
+  item: { waiting?: string },
+  e: Evidence,
+  defaultBranch: string | undefined,
+): Derived {
+  return { label: deriveLabel(item, e, defaultBranch), lastActivity: lastActivity(e) }
+}
+
+/** Failing check conclusions as GitHub reports them for check runs and status contexts. */
+const FAILING = new Set(['FAILURE', 'TIMED_OUT', 'STARTUP_FAILURE', 'ERROR'])
+
+export function countFailingChecks(rollup: unknown): number {
+  if (!Array.isArray(rollup)) return 0
+  let n = 0
+  for (const c of rollup as Record<string, unknown>[]) {
+    const v = String(c.conclusion ?? c.state ?? '').toUpperCase()
+    if (FAILING.has(v)) n++
+  }
+  return n
+}

package/src/errors.ts

@@ -0,0 +1,2 @@
+/** An error whose message is meant to be shown to the user as is. */
+export class RanniError extends Error {}

package/src/git.ts

@@ -0,0 +1,173 @@
+import { mentions } from './derive'
+import type { Runner } from './runner'
+import type { BranchEvidence, CommitEvidence, GitEvidence } from './types'
+
+export interface RefInfo extends BranchEvidence {
+  /** Short name without the remote prefix, used for identity matching. */
+  bare: string
+  full: string
+  /** Reachable from the default branch tip. Set only in Git-only mode. */
+  inDefault?: boolean
+}
+
+export interface RepoGit {
+  available: boolean
+  reason?: string
+  refs: RefInfo[]
+  /** Commits that carry at least one Work: trailer. */
+  trailers: { sha: string; date: string; value: string }[]
+  /** Default branch short name as origin/HEAD reports it (or main/master as a last resort). */
+  defaultBranch?: string
+  defaultTip?: string
+  /** Work: trailer commits on the default branch. Set only in Git-only mode. */
+  defaultCommits?: Set<string>
+}
+
+const NO_GIT: RepoGit = { available: false, refs: [], trailers: [] }
+
+/** One for-each-ref read and one log read. Both are bounded by the repository's own size. */
+export async function readRepoGit(run: Runner, cwd: string): Promise<RepoGit> {
+  const refsRes = await run(
+    'git',
+    [
+      'for-each-ref',
+      '--format=%(refname)%09%(objectname)%09%(committerdate:iso-strict)%09%(symref)',
+      'refs/heads',
+      'refs/remotes',
+    ],
+    { cwd },
+  )
+  if (refsRes.missing) return { ...NO_GIT, reason: 'git is not installed' }
+  if (refsRes.code !== 0) {
+    return { ...NO_GIT, reason: `not a Git repository (${firstLine(refsRes.stderr)})` }
+  }
+  const { refs, originHead } = parseRefs(refsRes.stdout)
+
+  const logRes = await run(
+    'git',
+    [
+      'log',
+      '--all',
+      '--no-color',
+      '--format=%H%x1f%cI%x1f%(trailers:key=Work,valueonly,unfold,separator=%x1d)%x1e',
+    ],
+    { cwd },
+  )
+  // A repository without commits has no log; that is evidence of nothing, not a failure.
+  const trailers = logRes.code === 0 ? parseLog(logRes.stdout) : []
+
+  let defaultBranch = originHead
+  if (!defaultBranch) {
+    const local = ['main', 'master'].find(n => refs.some(r => !r.remote && r.bare === n))
+    defaultBranch = local
+  }
+  const tipRef = defaultBranch ? findDefaultRef(refs, defaultBranch) : undefined
+  return {
+    available: true,
+    refs,
+    trailers,
+    defaultBranch,
+    defaultTip: tipRef?.tip,
+  }
+}
+
+function firstLine(s: string): string {
+  return s.trim().split('\n')[0] ?? ''
+}
+
+export function parseRefs(out: string): { refs: RefInfo[]; originHead?: string } {
+  const refs: RefInfo[] = []
+  let originHead: string | undefined
+  for (const line of out.split('\n')) {
+    if (!line) continue
+    const [full, tip, date, symref] = line.split('\t')
+    if (!full) continue
+    if (full.startsWith('refs/remotes/')) {
+      const rest = full.slice('refs/remotes/'.length)
+      const slash = rest.indexOf('/')
+      const remote = rest.slice(0, slash)
+      const bare = rest.slice(slash + 1)
+      if (symref) {
+        if (remote === 'origin' && bare === 'HEAD') {
+          originHead = symref.replace(/^refs\/remotes\/origin\//, '')
+        }
+        continue
+      }
+      if (bare === 'HEAD') continue
+      refs.push({ full, name: rest, bare, remote: true, tip, date })
+    } else if (full.startsWith('refs/heads/')) {
+      const bare = full.slice('refs/heads/'.length)
+      refs.push({ full, name: bare, bare, remote: false, tip, date })
+    }
+  }
+  return { refs, originHead }
+}
+
+export function parseLog(out: string): RepoGit['trailers'] {
+  const res: RepoGit['trailers'] = []
+  for (const rec of out.split('\x1e')) {
+    const [sha, date, value] = rec.replace(/^\n+/, '').split('\x1f')
+    if (!sha || !value || !value.trim()) continue
+    res.push({ sha, date, value: value.replace(/\x1d/g, '\n') })
+  }
+  return res
+}
+
+function findDefaultRef(refs: RefInfo[], name: string): RefInfo | undefined {
+  return refs.find(r => r.full === `refs/remotes/origin/${name}`) ?? refs.find(r => r.full === `refs/heads/${name}`)
+}
+
+export interface MergedRead {
+  /** Full names of refs fully merged into the default branch. */
+  refs: Set<string>
+  /** Commits on the default branch whose message has a Work: line. */
+  commits: Set<string>
+}
+
+/**
+ * Git-only mode: which refs and Work: trailer commits are on the default branch. Two
+ * extra reads, made only when the Git host is unavailable. The commit read keeps a work
+ * item ready to close after its merged branch is deleted.
+ */
+export async function readMerged(run: Runner, cwd: string, repo: RepoGit): Promise<MergedRead> {
+  const none: MergedRead = { refs: new Set(), commits: new Set() }
+  if (!repo.defaultBranch) return none
+  const ref = findDefaultRef(repo.refs, repo.defaultBranch)
+  if (!ref) return none
+  const [refsRes, commitsRes] = await Promise.all([
+    run('git', ['for-each-ref', `--merged=${ref.full}`, '--format=%(refname)', 'refs/heads', 'refs/remotes'], { cwd }),
+    run('git', ['rev-list', '--regexp-ignore-case', '--extended-regexp', '--grep=^[[:space:]]*Work:', ref.full], { cwd }),
+  ])
+  const lines = (s: string) => new Set(s.split('\n').map(l => l.trim()).filter(Boolean))
+  return {
+    refs: refsRes.code === 0 ? lines(refsRes.stdout) : new Set(),
+    commits: commitsRes.code === 0 ? lines(commitsRes.stdout) : new Set(),
+  }
+}
+
+/**
+ * Evidence for one identity out of the repository-wide reads. A branch counts as merged
+ * only when it is fully merged into the default branch and is not merely sitting on the
+ * default tip: a fresh, empty branch is trivially merged. A fast-forwarded branch still
+ * counts when commits carry the identity in a Work: trailer.
+ */
+export function gitEvidenceFor(repo: RepoGit, id: string): GitEvidence {
+  const commits: CommitEvidence[] = repo.trailers
+    .filter(t => mentions(t.value, id))
+    .map(t => ({ sha: t.sha, date: t.date, ...(repo.defaultCommits ? { merged: repo.defaultCommits.has(t.sha) } : {}) }))
+  const branches: BranchEvidence[] = repo.refs
+    .filter(r => mentions(r.bare, id))
+    .map(r => ({
+      name: r.name,
+      remote: r.remote,
+      tip: r.tip,
+      date: r.date,
+      merged: r.inDefault === undefined ? undefined : r.inDefault && (r.tip !== repo.defaultTip || commits.length > 0),
+    }))
+  return { branches, commits }
+}
+
+export function markMerged(repo: RepoGit, merged: MergedRead): void {
+  for (const r of repo.refs) r.inDefault = merged.refs.has(r.full)
+  repo.defaultCommits = merged.commits
+}

package/src/host.ts

@@ -0,0 +1,144 @@
+import { countFailingChecks, declaresWork, mentions } from './derive'
+import type { Runner } from './runner'
+import type { PullRequestEvidence, ReviewDecision } from './types'
+
+export const PR_LIMIT = 200
+/** Upper bound of open pull requests whose review threads are fetched in one call. */
+export const THREAD_PR_LIMIT = 50
+
+export interface HostRead {
+  available: boolean
+  /** Why the host evidence is missing. */
+  reason?: string
+  defaultBranch?: string
+  owner?: string
+  repo?: string
+  /** Every listed pull request, unfiltered. */
+  pullRequests: (PullRequestEvidence & { body: string; head: string })[]
+  /** True when the listing hit the limit and older pull requests may be missing. */
+  truncated: boolean
+}
+
+const NONE: HostRead = { available: false, pullRequests: [], truncated: false }
+
+export function classifyGhFailure(stderr: string, missing: boolean): string {
+  if (missing) return 'gh is not installed'
+  const s = stderr.trim()
+  if (/no git remotes|none of the git remotes|not a git repository|could not resolve to a repository/i.test(s)) {
+    return 'this repository has no GitHub remote'
+  }
+  if (/auth|log in|login|token|credentials|401|403/i.test(s)) return 'gh is not authenticated (run `gh auth login`)'
+  if (/resolve host|network|timed? ?out|dial tcp|connection|offline/i.test(s)) return 'no network to reach the Git host'
+  return `gh failed: ${s.split('\n')[0] || 'no output'}`
+}
+
+export async function readHost(run: Runner, cwd: string): Promise<HostRead> {
+  const repoRes = await run('gh', ['repo', 'view', '--json', 'nameWithOwner,defaultBranchRef'], { cwd })
+  if (repoRes.code !== 0) return { ...NONE, reason: classifyGhFailure(repoRes.stderr, repoRes.missing) }
+  let defaultBranch: string | undefined
+  let owner: string | undefined
+  let repo: string | undefined
+  try {
+    const j = JSON.parse(repoRes.stdout) as { nameWithOwner?: string; defaultBranchRef?: { name?: string } }
+    defaultBranch = j.defaultBranchRef?.name
+    const [o, r] = (j.nameWithOwner ?? '').split('/')
+    owner = o
+    repo = r
+  } catch {
+    return { ...NONE, reason: 'gh repo view returned unreadable output' }
+  }
+
+  const prRes = await run(
+    'gh',
+    [
+      'pr',
+      'list',
+      '--state',
+      'all',
+      '--limit',
+      String(PR_LIMIT),
+      '--json',
+      'number,title,body,headRefName,baseRefName,state,isDraft,reviewDecision,statusCheckRollup,url',
+    ],
+    { cwd },
+  )
+  if (prRes.code !== 0) return { ...NONE, reason: classifyGhFailure(prRes.stderr, prRes.missing) }
+  let list: Record<string, unknown>[]
+  try {
+    list = JSON.parse(prRes.stdout)
+    if (!Array.isArray(list)) throw new Error('not a list')
+  } catch {
+    return { ...NONE, reason: 'gh pr list returned unreadable output' }
+  }
+  return {
+    available: true,
+    defaultBranch,
+    owner,
+    repo,
+    pullRequests: list.map(parsePr),
+    truncated: list.length >= PR_LIMIT,
+  }
+}
+
+export function parsePr(p: Record<string, unknown>): PullRequestEvidence & { body: string; head: string } {
+  const state = String(p.state ?? '').toUpperCase()
+  return {
+    number: Number(p.number),
+    title: String(p.title ?? ''),
+    body: String(p.body ?? ''),
+    head: String(p.headRefName ?? ''),
+    url: String(p.url ?? ''),
+    state: state === 'MERGED' ? 'MERGED' : state === 'CLOSED' ? 'CLOSED' : 'OPEN',
+    isDraft: p.isDraft === true,
+    baseRef: String(p.baseRefName ?? ''),
+    reviewDecision: String(p.reviewDecision ?? '') as ReviewDecision,
+    failingChecks: countFailingChecks(p.statusCheckRollup),
+  }
+}
+
+/**
+ * Pull requests tied to the identity: mentioned in the title or head branch, or declared on
+ * a `Work:` line in the body. A plain body mention is not evidence, so a PR saying
+ * "depends on WORK-041" never makes WORK-041 look landed.
+ */
+export function prsFor<T extends { title: string; body: string; head: string }>(prs: T[], id: string): T[] {
+  return prs.filter(p => mentions(p.title, id) || mentions(p.head, id) || declaresWork(p.body, id))
+}
+
+/**
+ * Unresolved review threads for the given open pull requests, in one bounded GraphQL
+ * call. Returns undefined for a pull request whose count could not be read.
+ */
+export async function readThreads(
+  run: Runner,
+  cwd: string,
+  host: Pick<HostRead, 'owner' | 'repo'>,
+  numbers: number[],
+): Promise<{ counts: Map<number, number>; error?: string; skipped: number }> {
+  const counts = new Map<number, number>()
+  if (numbers.length === 0) return { counts, skipped: 0 }
+  const take = numbers.slice(0, THREAD_PR_LIMIT)
+  const skipped = numbers.length - take.length
+  if (!host.owner || !host.repo || !/^[\w.-]+$/.test(host.owner) || !/^[\w.-]+$/.test(host.repo)) {
+    return { counts, error: 'repository owner or name unavailable', skipped }
+  }
+  const fields = take
+    .map(n => `p${n}: pullRequest(number: ${Number(n)}) { reviewThreads(first: 100) { nodes { isResolved } } }`)
+    .join(' ')
+  const query = `query { repository(owner: "${host.owner}", name: "${host.repo}") { ${fields} } }`
+  const res = await run('gh', ['api', 'graphql', '-f', `query=${query}`], { cwd })
+  if (res.code !== 0) return { counts, error: classifyGhFailure(res.stderr, res.missing), skipped }
+  try {
+    const j = JSON.parse(res.stdout) as {
+      data?: { repository?: Record<string, { reviewThreads?: { nodes?: { isResolved?: boolean }[] } } | null> }
+    }
+    const repo = j.data?.repository ?? {}
+    for (const n of take) {
+      const nodes = repo[`p${n}`]?.reviewThreads?.nodes
+      if (Array.isArray(nodes)) counts.set(n, nodes.filter(t => t.isResolved === false).length)
+    }
+  } catch {
+    return { counts, error: 'review thread response was unreadable', skipped }
+  }
+  return { counts, skipped }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+import { main } from './cli'
+
+const code = await main(process.argv.slice(2), process.cwd(), {
+  out: s => process.stdout.write(s),
+  err: s => process.stderr.write(s),
+})
+process.exit(code)