@sagmans/dsh-plannotator 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +174 -0
- package/cordis.patch.yml +26 -0
- package/dist/args.d.ts +94 -0
- package/dist/args.js +142 -0
- package/dist/binary.d.ts +57 -0
- package/dist/binary.js +101 -0
- package/dist/cli.d.ts +66 -0
- package/dist/cli.js +131 -0
- package/dist/commands.d.ts +41 -0
- package/dist/commands.js +328 -0
- package/dist/config.d.ts +90 -0
- package/dist/config.js +115 -0
- package/dist/constants.d.ts +95 -0
- package/dist/constants.js +95 -0
- package/dist/decisions.d.ts +78 -0
- package/dist/decisions.js +170 -0
- package/dist/feedback.d.ts +58 -0
- package/dist/feedback.js +83 -0
- package/dist/index.d.ts +58 -0
- package/dist/index.js +45 -0
- package/dist/plan-source.d.ts +29 -0
- package/dist/plan-source.js +59 -0
- package/dist/transcript.d.ts +38 -0
- package/dist/transcript.js +45 -0
- package/dist/workspace.d.ts +70 -0
- package/dist/workspace.js +81 -0
- package/package.json +96 -0
package/dist/cli.js
ADDED
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Run the CLI and capture what it decided.
|
|
3
|
+
*
|
|
4
|
+
* A review is a long-lived child: it blocks until a human acts, and this
|
|
5
|
+
* process must stay responsive and cancellable meanwhile. The runner therefore
|
|
6
|
+
* owns exactly four things — argv-only spawning, bounded capture, cancellation
|
|
7
|
+
* with a kill ladder, and an optional timeout — and reports the outcome as the
|
|
8
|
+
* CLI's own exit code plus its two streams, so decision mapping stays a pure
|
|
9
|
+
* function over that result.
|
|
10
|
+
*
|
|
11
|
+
* @module dsh-plannotator/cli
|
|
12
|
+
*/
|
|
13
|
+
import { spawn } from 'node:child_process';
|
|
14
|
+
import { KILL_GRACE_MS, STREAM_CAP_BYTES } from "./constants.js";
|
|
15
|
+
/** Collects a stream while keeping memory bounded. */
|
|
16
|
+
class StreamCapture {
|
|
17
|
+
chunks = [];
|
|
18
|
+
bytes = 0;
|
|
19
|
+
cap;
|
|
20
|
+
overflowed = false;
|
|
21
|
+
constructor(cap = STREAM_CAP_BYTES) {
|
|
22
|
+
this.cap = cap;
|
|
23
|
+
}
|
|
24
|
+
push(chunk) {
|
|
25
|
+
if (this.bytes >= this.cap) {
|
|
26
|
+
this.overflowed = true;
|
|
27
|
+
return;
|
|
28
|
+
}
|
|
29
|
+
this.chunks.push(chunk);
|
|
30
|
+
this.bytes += Buffer.byteLength(chunk, 'utf8');
|
|
31
|
+
}
|
|
32
|
+
snapshot() {
|
|
33
|
+
const joined = this.chunks.join('');
|
|
34
|
+
if (!this.overflowed && Buffer.byteLength(joined, 'utf8') <= this.cap) {
|
|
35
|
+
return { text: joined, truncated: false };
|
|
36
|
+
}
|
|
37
|
+
// Cutting by bytes can split a UTF-8 sequence, so the kept text is sliced
|
|
38
|
+
// from the end and re-decoded rather than indexed.
|
|
39
|
+
const buffer = Buffer.from(joined, 'utf8').subarray(0, this.cap);
|
|
40
|
+
return { text: buffer.toString('utf8'), truncated: true };
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Spawn the CLI and settle once it has exited, failed, been cancelled, or hit
|
|
45
|
+
* the timeout.
|
|
46
|
+
*
|
|
47
|
+
* The returned promise never rejects: a missing or unspawnable binary is an
|
|
48
|
+
* outcome the command reports, not an exception the registry has to survive.
|
|
49
|
+
*
|
|
50
|
+
* @param request - argv, directory, environment, stdin, timeout, and signal.
|
|
51
|
+
* @returns how the run ended.
|
|
52
|
+
*/
|
|
53
|
+
export function runPlannotator(request) {
|
|
54
|
+
return new Promise((settle) => {
|
|
55
|
+
const stdout = new StreamCapture();
|
|
56
|
+
const stderr = new StreamCapture();
|
|
57
|
+
let settled = false;
|
|
58
|
+
let cancelled = false;
|
|
59
|
+
let killTimer;
|
|
60
|
+
let timeoutTimer;
|
|
61
|
+
const finish = (result) => {
|
|
62
|
+
if (settled)
|
|
63
|
+
return;
|
|
64
|
+
settled = true;
|
|
65
|
+
if (killTimer !== undefined)
|
|
66
|
+
clearTimeout(killTimer);
|
|
67
|
+
if (timeoutTimer !== undefined)
|
|
68
|
+
clearTimeout(timeoutTimer);
|
|
69
|
+
request.signal?.removeEventListener('abort', onAbort);
|
|
70
|
+
settle(result);
|
|
71
|
+
};
|
|
72
|
+
const child = spawn(request.binary, [...request.argv], {
|
|
73
|
+
cwd: request.cwd,
|
|
74
|
+
env: request.env,
|
|
75
|
+
// No shell: a path or a reviewer's words must never be re-parsed as syntax.
|
|
76
|
+
shell: false,
|
|
77
|
+
stdio: ['pipe', 'pipe', 'pipe'],
|
|
78
|
+
});
|
|
79
|
+
/** Escalate to SIGKILL after a grace period; a hung server must not hold the session. */
|
|
80
|
+
const terminate = () => {
|
|
81
|
+
child.kill('SIGTERM');
|
|
82
|
+
killTimer = setTimeout(() => {
|
|
83
|
+
child.kill('SIGKILL');
|
|
84
|
+
}, KILL_GRACE_MS);
|
|
85
|
+
killTimer.unref();
|
|
86
|
+
};
|
|
87
|
+
function onAbort() {
|
|
88
|
+
cancelled = true;
|
|
89
|
+
terminate();
|
|
90
|
+
}
|
|
91
|
+
child.stdout.setEncoding('utf8');
|
|
92
|
+
child.stderr.setEncoding('utf8');
|
|
93
|
+
child.stdout.on('data', (chunk) => stdout.push(chunk));
|
|
94
|
+
child.stderr.on('data', (chunk) => stderr.push(chunk));
|
|
95
|
+
child.on('error', (error) => {
|
|
96
|
+
finish({ kind: 'spawn-failed', message: error.message });
|
|
97
|
+
});
|
|
98
|
+
child.on('close', (code, signal) => {
|
|
99
|
+
if (cancelled) {
|
|
100
|
+
finish({ kind: 'exited', code: code ?? -1, cancelled: true, stdout: stdout.snapshot(), stderr: stderr.snapshot() });
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
if (code === null) {
|
|
104
|
+
finish({ kind: 'signalled', signal, cancelled: false, stdout: stdout.snapshot(), stderr: stderr.snapshot() });
|
|
105
|
+
return;
|
|
106
|
+
}
|
|
107
|
+
finish({ kind: 'exited', code, cancelled: false, stdout: stdout.snapshot(), stderr: stderr.snapshot() });
|
|
108
|
+
});
|
|
109
|
+
if (request.signal !== undefined) {
|
|
110
|
+
if (request.signal.aborted)
|
|
111
|
+
onAbort();
|
|
112
|
+
else
|
|
113
|
+
request.signal.addEventListener('abort', onAbort, { once: true });
|
|
114
|
+
}
|
|
115
|
+
if (request.timeoutMs > 0) {
|
|
116
|
+
timeoutTimer = setTimeout(() => {
|
|
117
|
+
terminate();
|
|
118
|
+
finish({ kind: 'timed-out', stdout: stdout.snapshot(), stderr: stderr.snapshot() });
|
|
119
|
+
}, request.timeoutMs);
|
|
120
|
+
timeoutTimer.unref();
|
|
121
|
+
}
|
|
122
|
+
// The child's stdin is always closed: a CLI waiting on a hook payload that
|
|
123
|
+
// will never arrive would otherwise hang until the timeout it may not have.
|
|
124
|
+
if (child.stdin !== null) {
|
|
125
|
+
if (request.stdin !== undefined)
|
|
126
|
+
child.stdin.end(request.stdin);
|
|
127
|
+
else
|
|
128
|
+
child.stdin.end();
|
|
129
|
+
}
|
|
130
|
+
});
|
|
131
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The four human commands, and the one place a review is actually run.
|
|
3
|
+
*
|
|
4
|
+
* Each handler follows the same shape — vet the input, resolve the executable,
|
|
5
|
+
* run one child, map its verdict, tell the model, notice the reader — because
|
|
6
|
+
* the differences between the surfaces are only their argv and what counts as a
|
|
7
|
+
* target. Keeping that shape in one helper is what makes the error paths
|
|
8
|
+
* uniform: a missing binary, a cancelled review, and a refused flag all reach
|
|
9
|
+
* the reader as the same kind of notice.
|
|
10
|
+
*
|
|
11
|
+
* @module dsh-plannotator/commands
|
|
12
|
+
*/
|
|
13
|
+
import type { Context } from '@deepseek-ai/cordis';
|
|
14
|
+
import { type BinaryProbe } from './binary.ts';
|
|
15
|
+
import { type PlannotatorConfig } from './config.ts';
|
|
16
|
+
import { writePlanSnapshot } from './workspace.ts';
|
|
17
|
+
/** What one review surface needs that is not in the config. */
|
|
18
|
+
export interface CommandDeps {
|
|
19
|
+
/** Resolved plugin config. */
|
|
20
|
+
readonly config: PlannotatorConfig;
|
|
21
|
+
/** Environment for binary lookup and for the child. */
|
|
22
|
+
readonly env: NodeJS.ProcessEnv;
|
|
23
|
+
/** Owner expected on the executable; `undefined` on platforms without one. */
|
|
24
|
+
readonly uid: number | undefined;
|
|
25
|
+
/** Filesystem probe for binary resolution. */
|
|
26
|
+
readonly probe: BinaryProbe;
|
|
27
|
+
/** Read the current time, so tests can pin snapshot names. */
|
|
28
|
+
readonly now: () => number;
|
|
29
|
+
/** Filesystem calls snapshot writing uses. */
|
|
30
|
+
readonly snapshotIo: Parameters<typeof writePlanSnapshot>[3];
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Register every plannotator command on the command registry.
|
|
34
|
+
*
|
|
35
|
+
* @param ctx - context carrying the command registry (and its logger).
|
|
36
|
+
* @param deps - config and the injectable environment.
|
|
37
|
+
* @returns disposer that unregisters and stops any review still running.
|
|
38
|
+
*/
|
|
39
|
+
export declare function registerPlannotatorCommands(ctx: Context, deps: CommandDeps): () => void;
|
|
40
|
+
/** The production dependency set, with the real clock and filesystem. */
|
|
41
|
+
export declare function defaultCommandDeps(config: PlannotatorConfig, env: NodeJS.ProcessEnv): CommandDeps;
|
package/dist/commands.js
ADDED
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The four human commands, and the one place a review is actually run.
|
|
3
|
+
*
|
|
4
|
+
* Each handler follows the same shape — vet the input, resolve the executable,
|
|
5
|
+
* run one child, map its verdict, tell the model, notice the reader — because
|
|
6
|
+
* the differences between the surfaces are only their argv and what counts as a
|
|
7
|
+
* target. Keeping that shape in one helper is what makes the error paths
|
|
8
|
+
* uniform: a missing binary, a cancelled review, and a refused flag all reach
|
|
9
|
+
* the reader as the same kind of notice.
|
|
10
|
+
*
|
|
11
|
+
* @module dsh-plannotator/commands
|
|
12
|
+
*/
|
|
13
|
+
import { existsSync, statSync } from 'node:fs';
|
|
14
|
+
import { isAbsolute, resolve } from 'node:path';
|
|
15
|
+
import { ANNOTATE_FLAGS, buildAnnotateArgs, buildAnnotateLastArgs, buildReviewArgs, classifyTarget, parseTypedLine, REVIEW_FLAGS, } from "./args.js";
|
|
16
|
+
import { NODE_BINARY_PROBE, resolveBinary, } from "./binary.js";
|
|
17
|
+
import { runPlannotator } from "./cli.js";
|
|
18
|
+
import { resolveDataDir, resolvePlansDir, } from "./config.js";
|
|
19
|
+
import { COMMAND_ANNOTATE, COMMAND_LAST, COMMAND_PLAN, COMMAND_REVIEW, } from "./constants.js";
|
|
20
|
+
import { outcomeFromAnnotate, outcomeFromAnnotateLast, outcomeFromReview, } from "./decisions.js";
|
|
21
|
+
import { feedbackFor, steerText } from "./feedback.js";
|
|
22
|
+
import { newestPlan } from "./plan-source.js";
|
|
23
|
+
import { newestAssistantText } from "./transcript.js";
|
|
24
|
+
import { planSnapshotPath, writePlanSnapshot } from "./workspace.js";
|
|
25
|
+
/** The session's working directory, which is what the review must run against. */
|
|
26
|
+
function sessionCwd(agent) {
|
|
27
|
+
const cwd = agent.session.header.cwd;
|
|
28
|
+
return typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd();
|
|
29
|
+
}
|
|
30
|
+
/** Resolve a typed path against the session's directory. */
|
|
31
|
+
function resolveTypedPath(cwd, token) {
|
|
32
|
+
return isAbsolute(token) ? token : resolve(cwd, token);
|
|
33
|
+
}
|
|
34
|
+
/** How a surface's notice reads once the review settled and feedback was routed. */
|
|
35
|
+
function notice(surface, outcome, steered) {
|
|
36
|
+
const approved = outcome.decision === 'approved';
|
|
37
|
+
const subject = surface === 'plan' ? 'plan' : surface === 'review' ? 'code review' : 'annotation';
|
|
38
|
+
if (approved)
|
|
39
|
+
return subject + ' approved';
|
|
40
|
+
if (steered)
|
|
41
|
+
return subject + ' feedback sent to the agent';
|
|
42
|
+
return subject + ' closed without feedback';
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Run one review and report it.
|
|
46
|
+
*
|
|
47
|
+
* @param options - the vetted target, argv, decision mapper, and shared state.
|
|
48
|
+
* @returns the command result the surface renders.
|
|
49
|
+
*/
|
|
50
|
+
async function runOne(options) {
|
|
51
|
+
const { ctx, deps, agent, surface } = options;
|
|
52
|
+
if (options.busy.current) {
|
|
53
|
+
return { kind: 'error', text: 'a plannotator review is already open; finish it before starting another' };
|
|
54
|
+
}
|
|
55
|
+
const cwd = sessionCwd(agent);
|
|
56
|
+
const resolution = resolveBinary({
|
|
57
|
+
configured: deps.config.binary,
|
|
58
|
+
allowUntrusted: deps.config.allowUntrustedBinary,
|
|
59
|
+
env: deps.env,
|
|
60
|
+
cwd,
|
|
61
|
+
uid: deps.uid,
|
|
62
|
+
probe: deps.probe,
|
|
63
|
+
});
|
|
64
|
+
if (!resolution.ok) {
|
|
65
|
+
return { kind: 'error', text: 'plannotator: ' + resolution.reason };
|
|
66
|
+
}
|
|
67
|
+
// The command's own signal is not enough: unloading the plugin has to stop a
|
|
68
|
+
// review too, so one controller owns the child for both cancellation paths.
|
|
69
|
+
const controller = new AbortController();
|
|
70
|
+
const forwardAbort = () => controller.abort();
|
|
71
|
+
if (options.signal.aborted)
|
|
72
|
+
controller.abort();
|
|
73
|
+
else
|
|
74
|
+
options.signal.addEventListener('abort', forwardAbort, { once: true });
|
|
75
|
+
options.inFlight.add(controller);
|
|
76
|
+
options.busy.current = true;
|
|
77
|
+
try {
|
|
78
|
+
const result = await runPlannotator({
|
|
79
|
+
binary: resolution.path,
|
|
80
|
+
argv: options.argv,
|
|
81
|
+
cwd,
|
|
82
|
+
env: deps.env,
|
|
83
|
+
stdin: options.stdin,
|
|
84
|
+
timeoutMs: deps.config.reviewTimeoutMs,
|
|
85
|
+
signal: controller.signal,
|
|
86
|
+
});
|
|
87
|
+
const mapped = options.map(result);
|
|
88
|
+
if (!mapped.ok) {
|
|
89
|
+
ctx.logger.warn(`${surface} review failed: ${mapped.error}`);
|
|
90
|
+
return { kind: 'error', text: 'plannotator: ' + mapped.error };
|
|
91
|
+
}
|
|
92
|
+
const message = deps.config.steerFeedback
|
|
93
|
+
? feedbackFor(mapped.outcome, options.target, deps.config.approveNotes)
|
|
94
|
+
: undefined;
|
|
95
|
+
if (message !== undefined)
|
|
96
|
+
steerText(agent, message);
|
|
97
|
+
return { kind: 'success', text: notice(surface, mapped.outcome, message !== undefined) };
|
|
98
|
+
}
|
|
99
|
+
finally {
|
|
100
|
+
options.signal.removeEventListener('abort', forwardAbort);
|
|
101
|
+
options.inFlight.delete(controller);
|
|
102
|
+
options.busy.current = false;
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Vet a typed target that must exist on disk.
|
|
107
|
+
*
|
|
108
|
+
* @param cwd - the session's directory.
|
|
109
|
+
* @param token - the typed operand.
|
|
110
|
+
* @param want - the kind of entry the surface accepts.
|
|
111
|
+
* @returns the absolute path, or the usage text to report.
|
|
112
|
+
*/
|
|
113
|
+
function existingPath(cwd, token, want) {
|
|
114
|
+
const path = resolveTypedPath(cwd, token);
|
|
115
|
+
if (!existsSync(path))
|
|
116
|
+
return { ok: false, error: path + ' does not exist' };
|
|
117
|
+
const facts = statSync(path);
|
|
118
|
+
if (want === 'file' && !facts.isFile())
|
|
119
|
+
return { ok: false, error: path + ' is not a file' };
|
|
120
|
+
return { ok: true, path };
|
|
121
|
+
}
|
|
122
|
+
/** Enforce the input bound before anything is written or piped. */
|
|
123
|
+
function oversize(text, limit) {
|
|
124
|
+
return Buffer.byteLength(text, 'utf8') > limit;
|
|
125
|
+
}
|
|
126
|
+
/** Read one positional at most, so a second operand fails loudly. */
|
|
127
|
+
function singleOperand(parsed) {
|
|
128
|
+
if (parsed.positionals.length === 0)
|
|
129
|
+
return undefined;
|
|
130
|
+
if (parsed.positionals.length === 1)
|
|
131
|
+
return parsed.positionals[0] ?? undefined;
|
|
132
|
+
return null;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Register every plannotator command on the command registry.
|
|
136
|
+
*
|
|
137
|
+
* @param ctx - context carrying the command registry (and its logger).
|
|
138
|
+
* @param deps - config and the injectable environment.
|
|
139
|
+
* @returns disposer that unregisters and stops any review still running.
|
|
140
|
+
*/
|
|
141
|
+
export function registerPlannotatorCommands(ctx, deps) {
|
|
142
|
+
const inFlight = new Set();
|
|
143
|
+
const busy = { current: false };
|
|
144
|
+
const plansDir = resolvePlansDir(resolveDataDir(deps.config, deps.env));
|
|
145
|
+
const definitions = [
|
|
146
|
+
{
|
|
147
|
+
name: COMMAND_PLAN,
|
|
148
|
+
description: 'Review the latest plan (or a markdown file) in the browser and return the decision',
|
|
149
|
+
input: { hint: '[file.md] [--markdown] [--no-jina] [--tailscale]' },
|
|
150
|
+
handler: async (invocation) => {
|
|
151
|
+
const parsed = parseTypedLine(invocation.rawInput.trim().split(/\s+/u), ANNOTATE_FLAGS);
|
|
152
|
+
if (!parsed.ok)
|
|
153
|
+
return { kind: 'error', text: parsed.error };
|
|
154
|
+
const operand = singleOperand(parsed.value);
|
|
155
|
+
if (operand === null)
|
|
156
|
+
return { kind: 'error', text: 'usage: /' + COMMAND_PLAN + ' [file.md]' };
|
|
157
|
+
let target;
|
|
158
|
+
if (operand !== undefined) {
|
|
159
|
+
if (classifyTarget(operand) !== 'path') {
|
|
160
|
+
return { kind: 'error', text: 'usage: /' + COMMAND_PLAN + ' [file.md] — a URL has no plan to review' };
|
|
161
|
+
}
|
|
162
|
+
const vetted = existingPath(sessionCwd(invocation.agent), operand, 'file');
|
|
163
|
+
if (!vetted.ok)
|
|
164
|
+
return { kind: 'error', text: vetted.error };
|
|
165
|
+
target = vetted.path;
|
|
166
|
+
}
|
|
167
|
+
else {
|
|
168
|
+
const plan = newestPlan(invocation.agent.session.snapshotEvents());
|
|
169
|
+
if (plan === undefined) {
|
|
170
|
+
return {
|
|
171
|
+
kind: 'error',
|
|
172
|
+
text: 'no plan in this session yet; pass a markdown file: /' + COMMAND_PLAN + ' plan.md',
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
if (oversize(plan, deps.config.maxInputBytes)) {
|
|
176
|
+
return { kind: 'error', text: 'the plan is larger than maxInputBytes; write it to a file and pass the path' };
|
|
177
|
+
}
|
|
178
|
+
// The snapshot path is what the reviewer's URL and the CLI's plan
|
|
179
|
+
// history both key on, so it is resolved before the run, not after.
|
|
180
|
+
const written = writePlanSnapshot(plansDir, invocation.agent.session.id, plan, deps.snapshotIo);
|
|
181
|
+
if (!written.ok) {
|
|
182
|
+
return { kind: 'error', text: 'could not write the plan snapshot: ' + written.error };
|
|
183
|
+
}
|
|
184
|
+
target = planSnapshotPath(plansDir, invocation.agent.session.id);
|
|
185
|
+
}
|
|
186
|
+
return runOne({
|
|
187
|
+
ctx,
|
|
188
|
+
deps,
|
|
189
|
+
agent: invocation.agent,
|
|
190
|
+
signal: invocation.signal,
|
|
191
|
+
surface: 'plan',
|
|
192
|
+
target,
|
|
193
|
+
argv: buildAnnotateArgs(target, { tailscale: deps.config.tailscale }),
|
|
194
|
+
stdin: undefined,
|
|
195
|
+
map: outcomeFromAnnotate,
|
|
196
|
+
inFlight,
|
|
197
|
+
busy,
|
|
198
|
+
});
|
|
199
|
+
},
|
|
200
|
+
},
|
|
201
|
+
{
|
|
202
|
+
name: COMMAND_REVIEW,
|
|
203
|
+
description: 'Review working-tree changes or a pull request in the browser',
|
|
204
|
+
input: { hint: '[--git|--gitbutler] [--base <ref>] [--diff-type <type>] [--no-local] [--tailscale] [PR_URL]' },
|
|
205
|
+
handler: async (invocation) => {
|
|
206
|
+
const parsed = parseTypedLine(invocation.rawInput.trim().split(/\s+/u), REVIEW_FLAGS);
|
|
207
|
+
if (!parsed.ok)
|
|
208
|
+
return { kind: 'error', text: parsed.error };
|
|
209
|
+
const operand = singleOperand(parsed.value);
|
|
210
|
+
if (operand === null) {
|
|
211
|
+
return { kind: 'error', text: 'usage: /' + COMMAND_REVIEW + ' [options] [PR_URL]' };
|
|
212
|
+
}
|
|
213
|
+
if (operand !== undefined && classifyTarget(operand) !== 'url') {
|
|
214
|
+
return {
|
|
215
|
+
kind: 'error',
|
|
216
|
+
text: 'usage: /' + COMMAND_REVIEW + ' [options] [PR_URL] — a code review reads the worktree or a PR URL',
|
|
217
|
+
};
|
|
218
|
+
}
|
|
219
|
+
const target = operand ?? sessionCwd(invocation.agent);
|
|
220
|
+
return runOne({
|
|
221
|
+
ctx,
|
|
222
|
+
deps,
|
|
223
|
+
agent: invocation.agent,
|
|
224
|
+
signal: invocation.signal,
|
|
225
|
+
surface: 'review',
|
|
226
|
+
target,
|
|
227
|
+
argv: buildReviewArgs(parsed.value, { tailscale: deps.config.tailscale }),
|
|
228
|
+
stdin: undefined,
|
|
229
|
+
map: outcomeFromReview,
|
|
230
|
+
inFlight,
|
|
231
|
+
busy,
|
|
232
|
+
});
|
|
233
|
+
},
|
|
234
|
+
},
|
|
235
|
+
{
|
|
236
|
+
name: COMMAND_ANNOTATE,
|
|
237
|
+
description: 'Annotate a markdown or text file, a folder, or a URL in the browser',
|
|
238
|
+
input: { hint: '<file|folder|https://…> [--markdown] [--no-jina] [--app] [--tailscale]' },
|
|
239
|
+
handler: async (invocation) => {
|
|
240
|
+
const parsed = parseTypedLine(invocation.rawInput.trim().split(/\s+/u), ANNOTATE_FLAGS);
|
|
241
|
+
if (!parsed.ok)
|
|
242
|
+
return { kind: 'error', text: parsed.error };
|
|
243
|
+
const operand = singleOperand(parsed.value);
|
|
244
|
+
if (operand === undefined || operand === null) {
|
|
245
|
+
return { kind: 'error', text: 'usage: /' + COMMAND_ANNOTATE + ' <file|folder|URL>' };
|
|
246
|
+
}
|
|
247
|
+
const kind = classifyTarget(operand);
|
|
248
|
+
if (kind === undefined) {
|
|
249
|
+
return { kind: 'error', text: 'usage: /' + COMMAND_ANNOTATE + ' <file|folder|URL>' };
|
|
250
|
+
}
|
|
251
|
+
let target = operand;
|
|
252
|
+
if (kind === 'path') {
|
|
253
|
+
const vetted = existingPath(sessionCwd(invocation.agent), operand, 'entry');
|
|
254
|
+
if (!vetted.ok)
|
|
255
|
+
return { kind: 'error', text: vetted.error };
|
|
256
|
+
target = vetted.path;
|
|
257
|
+
}
|
|
258
|
+
return runOne({
|
|
259
|
+
ctx,
|
|
260
|
+
deps,
|
|
261
|
+
agent: invocation.agent,
|
|
262
|
+
signal: invocation.signal,
|
|
263
|
+
surface: 'annotate',
|
|
264
|
+
target,
|
|
265
|
+
argv: buildAnnotateArgs(target, { tailscale: deps.config.tailscale }),
|
|
266
|
+
stdin: undefined,
|
|
267
|
+
map: outcomeFromAnnotate,
|
|
268
|
+
inFlight,
|
|
269
|
+
busy,
|
|
270
|
+
});
|
|
271
|
+
},
|
|
272
|
+
},
|
|
273
|
+
{
|
|
274
|
+
name: COMMAND_LAST,
|
|
275
|
+
description: 'Annotate the newest assistant message in the browser',
|
|
276
|
+
input: { hint: '(no arguments)' },
|
|
277
|
+
handler: async (invocation) => {
|
|
278
|
+
const parsed = parseTypedLine(invocation.rawInput.trim().split(/\s+/u), []);
|
|
279
|
+
if (!parsed.ok)
|
|
280
|
+
return { kind: 'error', text: parsed.error };
|
|
281
|
+
if (parsed.value.positionals.length > 0) {
|
|
282
|
+
return { kind: 'error', text: 'usage: /' + COMMAND_LAST + ' (no arguments)' };
|
|
283
|
+
}
|
|
284
|
+
const text = newestAssistantText(invocation.agent.session.deriveMessages());
|
|
285
|
+
if (text === undefined) {
|
|
286
|
+
return { kind: 'error', text: 'this session has no assistant message to annotate yet' };
|
|
287
|
+
}
|
|
288
|
+
if (oversize(text, deps.config.maxInputBytes)) {
|
|
289
|
+
return { kind: 'error', text: 'the message is larger than maxInputBytes; annotate a file instead' };
|
|
290
|
+
}
|
|
291
|
+
return runOne({
|
|
292
|
+
ctx,
|
|
293
|
+
deps,
|
|
294
|
+
agent: invocation.agent,
|
|
295
|
+
signal: invocation.signal,
|
|
296
|
+
surface: 'last',
|
|
297
|
+
target: 'the last assistant message',
|
|
298
|
+
argv: buildAnnotateLastArgs({ tailscale: deps.config.tailscale }),
|
|
299
|
+
stdin: text,
|
|
300
|
+
map: outcomeFromAnnotateLast,
|
|
301
|
+
inFlight,
|
|
302
|
+
busy,
|
|
303
|
+
});
|
|
304
|
+
},
|
|
305
|
+
},
|
|
306
|
+
];
|
|
307
|
+
const disposers = definitions.map((definition) => ctx.commands.register(definition));
|
|
308
|
+
ctx.logger.info('plannotator commands registered');
|
|
309
|
+
return () => {
|
|
310
|
+
for (const controller of inFlight)
|
|
311
|
+
controller.abort();
|
|
312
|
+
inFlight.clear();
|
|
313
|
+
// Registration disposers are idempotent; unloading twice is not an error.
|
|
314
|
+
for (const dispose of disposers)
|
|
315
|
+
dispose();
|
|
316
|
+
};
|
|
317
|
+
}
|
|
318
|
+
/** The production dependency set, with the real clock and filesystem. */
|
|
319
|
+
export function defaultCommandDeps(config, env) {
|
|
320
|
+
return {
|
|
321
|
+
config,
|
|
322
|
+
env,
|
|
323
|
+
uid: typeof process.getuid === 'function' ? process.getuid() : undefined,
|
|
324
|
+
probe: NODE_BINARY_PROBE,
|
|
325
|
+
now: Date.now,
|
|
326
|
+
snapshotIo: undefined,
|
|
327
|
+
};
|
|
328
|
+
}
|
package/dist/config.d.ts
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Plugin configuration: the row's `config` block, its defaults, and the two
|
|
3
|
+
* paths that are derived rather than configured.
|
|
4
|
+
*
|
|
5
|
+
* Defaults are data, not schema literals, because the loader validates through
|
|
6
|
+
* {@link Config} while a hand-built or re-normalized value goes through
|
|
7
|
+
* {@link normalizeConfig} — one table keeps the two from disagreeing.
|
|
8
|
+
*
|
|
9
|
+
* @module dsh-plannotator/config
|
|
10
|
+
*/
|
|
11
|
+
import z from '@deepseek-ai/schemastery';
|
|
12
|
+
/** How approved-plan notes are treated: forwarded as guidance, or dropped. */
|
|
13
|
+
export declare const APPROVE_NOTES_MODES: readonly ["steer", "ignore"];
|
|
14
|
+
export type ApproveNotesMode = (typeof APPROVE_NOTES_MODES)[number];
|
|
15
|
+
/** Every field the row may set, after defaults are applied. */
|
|
16
|
+
export interface PlannotatorConfig {
|
|
17
|
+
/** Absolute path to the plannotator executable; empty means resolve from env then PATH. */
|
|
18
|
+
readonly binary: string;
|
|
19
|
+
/** Data directory for plan snapshots; empty means env then `~/.plannotator`. */
|
|
20
|
+
readonly dataDir: string;
|
|
21
|
+
/** Hard ceiling on one review; 0 waits as long as the CLI server lives. */
|
|
22
|
+
readonly reviewTimeoutMs: number;
|
|
23
|
+
/** Publish every session over the tailnet instead of loopback. */
|
|
24
|
+
readonly tailscale: boolean;
|
|
25
|
+
/** Forward reviewer feedback to the model as a steering message. */
|
|
26
|
+
readonly steerFeedback: boolean;
|
|
27
|
+
/** Whether notes accompanying an approval are forwarded or dropped. */
|
|
28
|
+
readonly approveNotes: ApproveNotesMode;
|
|
29
|
+
/** Permit an executable this process does not own or that others can rewrite. */
|
|
30
|
+
readonly allowUntrustedBinary: boolean;
|
|
31
|
+
/** Largest plan or transcript text this plugin will hand to a review. */
|
|
32
|
+
readonly maxInputBytes: number;
|
|
33
|
+
}
|
|
34
|
+
/** The values a profile gets when it sets nothing. */
|
|
35
|
+
export declare const CONFIG_DEFAULTS: PlannotatorConfig;
|
|
36
|
+
/** Loader-facing schema; every field defaulted so a row config may name any subset. */
|
|
37
|
+
export declare const Config: z<Schemastery.ObjectS<{
|
|
38
|
+
binary: z<string, string>;
|
|
39
|
+
dataDir: z<string, string>;
|
|
40
|
+
reviewTimeoutMs: z<number, number>;
|
|
41
|
+
tailscale: z<boolean, boolean>;
|
|
42
|
+
steerFeedback: z<boolean, boolean>;
|
|
43
|
+
approveNotes: z<"ignore" | "steer", "ignore" | "steer">;
|
|
44
|
+
allowUntrustedBinary: z<boolean, boolean>;
|
|
45
|
+
maxInputBytes: z<number, number>;
|
|
46
|
+
}>, Schemastery.ObjectT<{
|
|
47
|
+
binary: z<string, string>;
|
|
48
|
+
dataDir: z<string, string>;
|
|
49
|
+
reviewTimeoutMs: z<number, number>;
|
|
50
|
+
tailscale: z<boolean, boolean>;
|
|
51
|
+
steerFeedback: z<boolean, boolean>;
|
|
52
|
+
approveNotes: z<"ignore" | "steer", "ignore" | "steer">;
|
|
53
|
+
allowUntrustedBinary: z<boolean, boolean>;
|
|
54
|
+
maxInputBytes: z<number, number>;
|
|
55
|
+
}>>;
|
|
56
|
+
/**
|
|
57
|
+
* Apply defaults to a config object the loader did not validate.
|
|
58
|
+
*
|
|
59
|
+
* The loader validates the row's config, but a directly-imported `apply` (tests,
|
|
60
|
+
* an embedding host) gets whatever the caller passed; a missing field would
|
|
61
|
+
* otherwise read as `undefined` and turn into the string "undefined" on a
|
|
62
|
+
* command line.
|
|
63
|
+
*
|
|
64
|
+
* @param raw - candidate config, of unknown provenance.
|
|
65
|
+
* @returns a complete config; unknown or malformed fields fall back to defaults.
|
|
66
|
+
*/
|
|
67
|
+
export declare function normalizeConfig(raw: unknown): PlannotatorConfig;
|
|
68
|
+
/**
|
|
69
|
+
* Resolve the directory plan snapshots are written under.
|
|
70
|
+
*
|
|
71
|
+
* Config outranks the environment because a profile can pin a location the
|
|
72
|
+
* reader chose, while the environment is how a one-off run redirects it.
|
|
73
|
+
*
|
|
74
|
+
* @param config - resolved plugin config.
|
|
75
|
+
* @param env - process environment.
|
|
76
|
+
* @param home - the user's home directory.
|
|
77
|
+
* @returns the absolute data directory (it may not exist yet).
|
|
78
|
+
*/
|
|
79
|
+
export declare function resolveDataDir(config: PlannotatorConfig, env: NodeJS.ProcessEnv, home?: string): string;
|
|
80
|
+
/**
|
|
81
|
+
* Resolve the directory plan snapshots are written into.
|
|
82
|
+
*
|
|
83
|
+
* One path per session is what lets the CLI's own plan history and diff work:
|
|
84
|
+
* a resubmitted plan overwrites the same document, so the browser can show what
|
|
85
|
+
* changed since the last review.
|
|
86
|
+
*
|
|
87
|
+
* @param dataDir - the resolved data directory.
|
|
88
|
+
* @returns the directory holding this plugin's plan snapshots.
|
|
89
|
+
*/
|
|
90
|
+
export declare function resolvePlansDir(dataDir: string): string;
|