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/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,7 @@ jobs:
packages/editor/App.editModeCrossBlockHighlights.test.tsx
packages/editor/App.markdownUnanchored.test.tsx
packages/editor/App.documentDrafts.test.tsx
packages/editor/App.bundle.test.tsx
packages/editor/annotationDraftStaleRetry.test.tsx
packages/ui/components/blocks/AlertBlock.title.test.tsx
packages/ui/components/blocks/AlertBlock.seam.test.tsx
Expand Down
66 changes: 50 additions & 16 deletions AGENTS.md

Large diffs are not rendered by default.

74 changes: 72 additions & 2 deletions apps/hook/hooks/mod/controller.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test'
import { PlannotatorMod, STORE_LAUNCHES } from './controller'
import { PLAN_APPROVAL_NEXT_STEP } from './delivery'
import { CLASSIC_PLAN_REVIEW_TEXT } from './plan'
import { PLANNOTATOR_BUNDLE_HINT_LINE, PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT } from './tool'
import { fakeHost, type FakeHost, type RunCall } from './testing/fake-host'

const SESSION = { sessionId: 'session-1', dataDir: '/data', interactive: true }
Expand Down Expand Up @@ -853,12 +854,11 @@ describe('the plannotator tool: list and close (contract v2)', () => {
expect(host.submits[0]).toContain('fix line 3')
})

test('several files and reply answer with an error and launch nothing yet', async () => {
test('reply answers with an error and launches nothing yet', async () => {
const host = fakeHost()
serveOnLaunch(host)
const mod = new PlannotatorMod(host, SESSION)

expect('deny' in (await mod.runTool({ action: 'annotate', target: ['a.md', 'b.md'] }))).toBe(true)
expect('deny' in (await mod.runTool({ action: 'reply', session: 'pn-ababab', comment: 'c1', text: 'done' }))).toBe(true)
expect(launches(host)).toHaveLength(0)

Expand All @@ -867,3 +867,73 @@ describe('the plannotator tool: list and close (contract v2)', () => {
expect(launches(host)[0]?.argv.slice(5)).toEqual(['plannotator', 'annotate', 'a.md'])
})
})

// Reviews of several files (bundles). The failures: a list launched as
// something other than the CLI's bundle invocation (re-split, reordered), the
// decision heading naming one file of several, or an older CLI's "pick one"
// error shown to Claude as if its call were wrong.
describe('the plannotator tool: several files', () => {
test('a list launches one CLI with the files in order, and the result and decision name the bundle', async () => {
const host = fakeHost()
serveOnLaunch(host)
const mod = new PlannotatorMod(host, SESSION)

const answer = await mod.runTool({ action: 'annotate', target: ['spec.md', 'ui/mock.html', 'notes.md'], gate: true })

expect('text' in answer && answer.text).toContain('Opened 3 files: spec.md, mock.html, notes.md in Plannotator')
const [launch] = launches(host)
expect(launch?.argv.slice(5)).toEqual(['plannotator', 'annotate', 'spec.md', 'ui/mock.html', 'notes.md', '--gate'])

decide(host, launch!, { surface: 'annotate', decision: 'annotated', message: 'two notes', noop: false, annotationCount: 2 })
await host.tick()
expect(host.submits[0]).toStartWith('Plannotator: 3 files: spec.md, mock.html, notes.md (pn-')
})

test('an older CLI refusing several paths reads as "update Plannotator", for the tool and the slash command', async () => {
const olderRefusal = [
'Ambiguous annotate arguments: 2 of them each resolve to an existing target.',
' a.md -> /r/a.md',
' b.md -> /r/b.md',
'Re-run with exactly one target: plannotator annotate <file.md | file.txt | file.html | https://... | folder/>',
].join('\n')
const host = fakeHost()
host.onRun = (call) => {
if (isLaunch(call)) {
host.files.set(`${launchDirOf(call)}/stderr`, olderRefusal)
host.files.set(`${launchDirOf(call)}/exit`, '1')
}
}
const mod = new PlannotatorMod(host, SESSION)

const answer = await mod.runTool({ action: 'annotate', target: ['a.md', 'b.md'] })
expect('deny' in answer && answer.deny).toBe(PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT)
expect(await mod.runCommand('annotate', 'a.md b.md')).toBe(PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT)
// Prose around two paths is the user's own ambiguity, shown as the CLI said it.
expect(await mod.runCommand('annotate', 'compare a.md and b.md')).toContain('Ambiguous annotate arguments')
})

test("a current CLI's ambiguity error (a URL among the files) is shown as it is", async () => {
const host = fakeHost()
host.onRun = (call) => {
if (isLaunch(call)) {
host.files.set(
`${launchDirOf(call)}/stderr`,
`Ambiguous annotate arguments: 2 of them each resolve to an existing target.\n${PLANNOTATOR_BUNDLE_HINT_LINE}`,
)
host.files.set(`${launchDirOf(call)}/exit`, '1')
}
}
const mod = new PlannotatorMod(host, SESSION)
const answer = await mod.runTool({ action: 'annotate', target: ['a.md', 'https://example.com'] })
expect('deny' in answer && answer.deny).toContain(PLANNOTATOR_BUNDLE_HINT_LINE)
})

test('the slash command names several file paths as a bundle', async () => {
const host = fakeHost()
serveOnLaunch(host, 5555)
const mod = new PlannotatorMod(host, SESSION)
const text = await mod.runCommand('annotate', 'spec.md notes.md')
expect(text).toContain('2 files: spec.md, notes.md')
expect(launches(host)[0]?.argv.slice(5)).toEqual(['plannotator', 'annotate', 'spec.md', 'notes.md'])
})
})
17 changes: 14 additions & 3 deletions apps/hook/hooks/mod/controller.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import {
cliArgvFor,
failedText,
fileIn,
isSeveralFilePaths,
launchArgv,
launchDirOf,
openedText,
Expand Down Expand Up @@ -48,7 +49,9 @@ import {
type PendingApproval,
} from './plan'
import {
isOlderCliBundleRefusal,
parsePlannotatorToolInput,
plannotatorBundleSubject,
plannotatorSessionId,
plannotatorToolArgs,
plannotatorToolCloseText,
Expand Down Expand Up @@ -411,6 +414,11 @@ export class PlannotatorMod {
const opened = await this.open(kind, rawArgs, subjectFor(kind, rawArgs))
switch (opened.state) {
case 'error':
// Several file paths given to a CLI that predates reviews of several
// files: say to update instead of showing its "pick one" error.
if (kind === 'annotate' && isOlderCliBundleRefusal(opened.text) && isSeveralFilePaths(wordsOf(rawArgs))) {
return PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT
}
return opened.text
case 'starting':
return `Starting Plannotator for ${opened.subject}… it opens in your browser when ready, and your feedback comes back here as a message.`
Expand Down Expand Up @@ -442,14 +450,17 @@ export class PlannotatorMod {
case 'last':
break
}
// Several files as one review need a CLI with bundles; none has them yet.
if (Array.isArray(call.target)) return { deny: PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT }
const action = call.action
const gate = call.gate === true
const subject = subjectFor(action, plannotatorToolTargets(call))
const targets = plannotatorToolTargets(call)
// A list of files is one review of all of them (a bundle), named as such.
const bundle = Array.isArray(call.target)
const subject = bundle ? plannotatorBundleSubject(targets) : subjectFor(action, targets)
const opened = await this.open(action, plannotatorToolArgs(call), subject, gate ? { deliverApproval: true } : {})
switch (opened.state) {
case 'error':
// An older CLI answers several paths with its ambiguity error.
if (bundle && isOlderCliBundleRefusal(opened.text)) return { deny: PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT }
return { deny: opened.text }
case 'starting':
return { text: plannotatorToolOpenedText(opened.subject, undefined, gate, opened.sessionId) }
Expand Down
13 changes: 13 additions & 0 deletions apps/hook/hooks/mod/launch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@

import type { SessionKind } from './delivery'
import { splitShellWords } from './shell-words'
import { looksLikeFilePath, plannotatorBundleSubject } from './tool'

/** The wrapper. `$1` is the launch directory; the CLI argv follows. */
export const LAUNCH_SCRIPT = [
Expand Down Expand Up @@ -238,6 +239,16 @@ function baseName(path: string): string {
return trimmed.slice(trimmed.lastIndexOf('/') + 1) || trimmed
}

/**
* Whether annotate's words (flags ignored) are several file paths, i.e. a
* review of several files (the CLI checks they exist; this only reads their
* shape, for naming the session and for reading an older CLI's refusal).
*/
export function isSeveralFilePaths(words: readonly string[]): boolean {
const targets = [...new Set(words.filter((word) => !word.startsWith('-')))]
return targets.length > 1 && targets.every(looksLikeFilePath)
}

/** How the status line, the command output and the plugin turn name a session. */
export function subjectFor(kind: SessionKind, args: string | readonly string[], version?: number): string {
const words = wordsOf(args).filter((word) => !word.startsWith('-'))
Expand All @@ -255,6 +266,8 @@ export function subjectFor(kind: SessionKind, args: string | readonly string[],
return directory ? `changes in ${baseName(directory)}` : 'local changes'
}
case 'annotate': {
// Several file paths open as one review: name it as a bundle.
if (isSeveralFilePaths(words)) return plannotatorBundleSubject([...new Set(words)])
const target = words.find((word) => /^https?:\/\//i.test(word) || /[./]/.test(word)) ?? words[0]
if (!target) return 'document'
if (/^https?:\/\//i.test(target)) {
Expand Down
92 changes: 77 additions & 15 deletions apps/hook/hooks/mod/tool.ts
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ export interface PlannotatorToolInput {

export const PLANNOTATOR_TOOL_DESCRIPTION = [
'Open Plannotator, the browser review UI, for the user, and return at once. Also lists and closes the reviews opened in this conversation (by this tool or the user\'s /plannotator-* commands).',
'- action "annotate": annotate a file (markdown, text, config, HTML), a folder, or a URL; `target` is required. `gate: true` adds an Approve button for an explicit sign-off. `options.markdown: true` converts HTML or a URL to markdown first.',
'- action "annotate": annotate a file (markdown, text, config, HTML), a folder, or a URL; `target` is required. Pass a list as `target` to review several files together, in the order you want them read. `gate: true` adds an Approve button for an explicit sign-off. `options.markdown: true` converts HTML or a URL to markdown first.',
'- action "review": review code changes; `target` is an optional repository directory or a GitHub/GitLab/Bitbucket pull request URL (default: the current repository). `options.base` sets the compare branch or ref (git only).',
'- action "last": annotate your own last assistant message; no target.',
'- action "list": the reviews opened in this conversation that are still open, one line each: session id, what it shows, url, age, state, and how many comments the reviewer has not sent yet.',
Expand All @@ -61,7 +61,7 @@ export const PLANNOTATOR_TOOL_INPUT_SCHEMA = {
{ type: 'string' },
{ type: 'array', items: { type: 'string' }, minItems: 1 },
],
description: 'annotate: the file, folder or URL (required). review: a repository directory or PR URL (optional). Other actions: not used.',
description: 'annotate: the file, folder or URL (required), or a list of file paths to review together in that order. review: a repository directory or PR URL (optional). Other actions: not used.',
},
gate: {
type: 'boolean',
Expand Down Expand Up @@ -261,14 +261,21 @@ export function plannotatorToolTargets(input: PlannotatorToolInput): string[] {

/**
* The arguments the matching slash command would carry (`/plannotator-annotate
* <these>`), one argument per element, never re-split. `last` has none, and
* neither do the actions that open nothing (list, close, reply).
* <these>`), one argument per element, never re-split. A list of annotate
* targets passes a bare word as `./word`, so the CLI reads every entry as a
* path. `last` has none, and neither do the actions that open nothing (list,
* close, reply).
*/
export function plannotatorToolArgs(input: PlannotatorToolInput): string[] {
switch (input.action) {
case 'annotate':
return [
...plannotatorToolTargets(input),
// A list is files named by their paths, so every entry is passed as
// one: a bare word becomes `./word`. The CLI then refuses a list with a
// missing file instead of reading the bare word as prose.
...(Array.isArray(input.target)
? input.target.map((target) => (looksLikeFilePath(target) || /^https?:\/\//i.test(target) ? target : `./${target}`))
: plannotatorToolTargets(input)),
...(input.gate ? ['--gate'] : []),
...(input.options?.markdown ? ['--markdown'] : []),
]
Expand Down Expand Up @@ -308,9 +315,56 @@ export function plannotatorDecisionHeading(subject: string, sessionId: string |
return `Plannotator: ${subject}${sessionId ? ` (${sessionId})` : ''} — ${outcome}.`
}

/** What a host answers a list of several files with until it can open them as one review. */
/** What a host answers a list of several files with when its Plannotator CLI is too old to open them as one review. */
export const PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT =
'Plannotator did not open: opening several files in one review needs a newer Plannotator. Open them one at a time for now, or ask the user to update Plannotator.'
'Plannotator did not open: the installed Plannotator is too old to open several files at once. Ask the user to update Plannotator to open several files at once, or open them one at a time for now.'

/**
* The line a CLI that opens bundles adds to its "Ambiguous annotate
* arguments" error (`ANNOTATE_BUNDLE_HINT` in annotate-target.ts; copied here
* because this section must stay dependency-free).
*/
export const PLANNOTATOR_BUNDLE_HINT_LINE =
'To review several files together, pass only their paths: plannotator annotate a.md b.html'

/**
* Whether a CLI's startup error for several file paths is an OLDER CLI's
* refusal: its ambiguity error without the bundle hint a current CLI adds. A
* host that sent a list of paths answers `PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT`
* then, instead of showing an error that tells the agent to pick one file.
*/
export function isOlderCliBundleRefusal(errorText: string): boolean {
return errorText.includes('Ambiguous annotate arguments:') && !errorText.includes(PLANNOTATOR_BUNDLE_HINT_LINE)
}

/** The file name of a path, for subjects (either separator). */
function fileNameOf(path: string): string {
const trimmed = path.replace(/[\\/]+$/, '')
return trimmed.slice(Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\')) + 1) || trimmed
}

/**
* What a review of several files is called wherever one line names it: the
* tool's result, the decision heading, the session list. Up to three file
* names, then a count of the rest: "3 files: spec.md, mock.html, notes.md",
* "5 files: a.md, b.md, c.md +2 more".
*/
export function plannotatorBundleSubject(paths: readonly string[]): string {
const names = paths.map(fileNameOf)
const rest = names.length - 3
return `${names.length} files: ${names.slice(0, 3).join(', ')}${rest > 0 ? ` +${rest} more` : ''}`
}

/**
* Whether a shell word reads as a file path rather than prose: it has a path
* separator, starts with `~`, `.` or `@`, or ends in a file extension. A URL
* is not a path. Pure: nothing is looked up on disk.
*/
export function looksLikeFilePath(word: string): boolean {
if (/^https?:\/\//i.test(word)) return false
if (/[\\/]/.test(word) || /^[~.@]/.test(word)) return true
return /\.[A-Za-z0-9]{1,12}$/.test(word)
}

/** What a host answers `reply` with until it delivers single comments. */
export const PLANNOTATOR_TOOL_REPLY_UNAVAILABLE_TEXT =
Expand Down Expand Up @@ -532,15 +586,18 @@ const COMMAND_ACTIONS: Record<string, PlannotatorToolAction> = {
* word is exactly `plannotator` (the installed binary on PATH; a path such as
* `./plannotator` is a dev build and runs for real), with subcommand
* `annotate`, `review`, `annotate-last` or `last`, carrying only what the tool
* represents: annotate `<target>` plus `--gate` and `--markdown`; review
* `[target]` plus `--base <ref>`; last with no arguments. `--json` is accepted
* and dropped (the decision arrives as a message, not on stdout). The result
* passes `parsePlannotatorToolInput`.
* represents: annotate `<target>` (or several targets that all read as file
* paths, `looksLikeFilePath`, which become `target: [...]`, a review of
* several files) plus `--gate` and `--markdown`; review `[target]` plus
* `--base <ref>`; last with no arguments. `--json` is accepted and dropped
* (the decision arrives as a message, not on stdout). The result passes
* `parsePlannotatorToolInput`.
*
* Everything else is null and runs as written: other subcommands, any other
* flag (`--require-approval`, `--result-file`, `--hook`, `--tailscale`,
* `--static`, `--app`, `--no-jina`, `--help`, ...), a repeated flag, more than
* one target, an environment prefix, and any shell syntax (`cd x && ...`,
* `--static`, `--app`, `--no-jina`, `--help`, ...), a repeated flag, several
* targets that are not all file paths (or for review), an environment prefix,
* and any shell syntax (`cd x && ...`,
* pipes, redirects, substitutions), so scripted strict gates keep the CLI.
*/
export function plannotatorCommandToToolInput(command: string): PlannotatorToolInput | null {
Expand Down Expand Up @@ -576,8 +633,13 @@ export function plannotatorCommandToToolInput(command: string): PlannotatorToolI
} else return null
}

if (targets.length > 1) return null
if (targets.length === 1) call.target = targets[0]
if (targets.length > 1) {
// Several targets are taken over only as a review of several files:
// annotate, and every word a file path. Anything else (prose around a
// path, which the CLI's tolerant resolution reads) runs as written.
if (action !== 'annotate' || !targets.every(looksLikeFilePath)) return null
call.target = targets
} else if (targets.length === 1) call.target = targets[0]
if (Object.keys(options).length > 0) call.options = options
const parsed = parsePlannotatorToolInput(call)
return parsed.ok ? parsed.input : null
Expand Down
Loading
Loading