* feat(#3970): per-task external-tracker content-resolution seam Implements ADR-3646 (Phase 1, #3970): a `<task tracker-id="...">` attribute plus a new optional `taskContentResolver` capability-manifest field let a capability resolve a task's action/verify/acceptance-criteria/read_first/done content from an external issue tracker instead of PLAN.md's inline body. - src/plan-document.cts: parses the `tracker-id` attribute into `PlanTask.trackerId` - src/task-content-resolution.cts: new leaf module — split/find/build/resolve, with a hard-halt (throw) contract on ambiguous/failed/timeout/malformed resolution, never a silent fallback to possibly-stale inline text - src/task-command-router.cts: new `task resolve-content --plan --task-id --raw` CLI verb wiring the module into a real process exit code - gsd-core/bin/lib/capability-validator.cjs: validates the new `taskContentResolver` manifest field (feature-role only, cross-capability trackerPrefix uniqueness) - gsd-core/workflows/execute-plan.md, gsd-core/references/loop-hook-dispatch.md, docs/reference/capability-manifest.md: wire the seam into the per-task loop and document it as a new `execute:task` point outside the existing contribution/step/gate vocabulary (unconditional in autonomous mode) Closes #3970 * fix(#3970): gate checkpoint tasks out of content resolution, close trackerPrefix grammar parity gap, cover path-traversal guard Standards/Spec code-review pass on the task-content-resolution seam (ADR-3646 Phase 1) found three defects: 1. execute-plan.md's task-content-resolution bullet fired on any tracker-id-bearing task with no check that it wasn't type="checkpoint:*", contradicting ADR-3646 Decision 1 (a checkpoint task must never enter resolve-content). plan-document.cts already parses trackerId: null unconditionally for checkpoint tasks; only the workflow prose needed the fix, so the bullet now explicitly excludes checkpoint tasks. 2. task-content-resolution.cts's parseResolverDeclaration accepted any non-empty trackerPrefix with no grammar check, while capability- validator.cjs's KEBAB_RE enforces kebab-case at install time — a Generative Fix Divergence gap. Added the same grammar (as a literal regex, documented as intentionally not shared across the .cts/.cjs build boundary) plus a parity test asserting the two surfaces agree across a valid/invalid trackerPrefix table. 3. task-command-router.cts's routeResolveContent path-traversal guard on --plan had zero test coverage. Added a test exercising a ../../../etc/passwit-shaped path and asserting the USAGE rejection names the offending path. * fix(#3970): sanitize resolver diagnostics and cap resolver timeoutMs Two findings caught by an isolated security-review pass on the task content resolution seam: - ResolverFailedError/ResolverMalformedOutputError embedded raw, unsanitized subprocess stderr/stdout (attacker/model-influenced via the tracker-id argv token) into .message. A hostile or buggy resolver could smuggle a newline plus a forged "Error: " line, or terminal escape sequences, into a diagnostic io.cjs's error() writes verbatim to stderr. Fixed at the constructor (task-content-resolution.cts) via io.cjs's existing formatDiagnosticToken(), so every caller of resolveTaskContent gets a safe .message by construction. - capability-validator.cjs's validateTaskContentResolverFields had no upper bound on taskContentResolver.invoke.timeoutMs, letting a manifest declare an effectively unbounded value and defeat the "bounded subprocess" design intent. Added a 120000ms ceiling specific to this field, without touching the shared isPositiveIntegerMs() helper (still used unbounded by the reviewer lane's timeoutFloorMs and probe timeoutMs). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(#3970): fix gsd-test failures — stale prose allowlist line and stderr-vs-message assertion gsd-test (remote dockerized matrix) came back red with 5 failures on this PR; all five are real defects, fixed here. - tests/no-bare-gsd-tools-command-position.test.cjs: PROSE_ALLOWLIST's execute-plan.md entry pointed at line 415, which ffc190df4's checkpoint-exclusion caveat (added near line 221) shifted down by one line. The actual "validated downstream by gsd-tools uat classify-coverage" descriptive mention now sits at line 416. Updated the allowlist entry's line number to match. - tests/task-command-router-resolve-content.test.cjs: the path-traversal test asserted the outside-project-scope diagnostic against the thrown ExitError's own .message. io.cts's error() (ADR-3889) writes its human-readable message to fd 2 via writeAllSync and then throws a bare `new ExitError(1)` with no message argument — by design, so the exception carries no duplicate text and the thrown ExitError's message defaults to "process exit 1" (cli-exit.cts's ExitError constructor). Root cause was the test, not the source: task-command-router.cjs's outside-project-scope rejection already calls error() correctly and the diagnostic text is genuinely emitted, just on fd 2, not on the exception. Fixed the test to capture fd-2 writes (mirroring tests/estimate-calibrate.test.cjs's runCalibrateExpectError and this same file's own captureStdout for fd 1) and assert against the captured stderr text instead of err.message. This was masked locally because a manual `node -e` sanity check that only inspects the caught exception's .message cannot see what the real node:test run actually failed on. Emitted-Drift-Ack-Growth: execute-plan.md — adds the ADR-3646 task-content-resolution bullet and checkpoint-exclusion caveat to the per-task execute loop; a real behavioral prose addition, not incidental bloat. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(#3970): backfill changeset PR number (pr:0 -> pr:4000) --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -2,9 +2,10 @@
|
||||
* Plan Document Module — the single parser for a `*-PLAN.md` document BODY.
|
||||
*
|
||||
* Owns: objective extraction, the task-block grammar (`<task>` elements, with
|
||||
* the legacy `## Task N` heading fallback), planned-file extraction, and the
|
||||
* frontmatter-derived scheduling metadata (`wave`, `depends_on`, `autonomous`,
|
||||
* `agent_hint`, `files_modified`).
|
||||
* the legacy `## Task N` heading fallback — including the optional `tracker-id`
|
||||
* attribute, ADR-3646 Phase 1, read verbatim and never split here), planned-file
|
||||
* extraction, and the frontmatter-derived scheduling metadata (`wave`,
|
||||
* `depends_on`, `autonomous`, `agent_hint`, `files_modified`).
|
||||
*
|
||||
* WHY THIS IS A LEAF MODULE. This logic was written inline inside
|
||||
* `cmdPhasePlanIndex` (`src/phase.cts`). Two commands in two different families
|
||||
@@ -67,6 +68,14 @@ interface PlanTask {
|
||||
acceptanceCriteria: string[];
|
||||
/** `<done>` text, or null. */
|
||||
done: string | null;
|
||||
/**
|
||||
* Verbatim `tracker-id` attribute value (e.g. `beads:GSD-42`), or null.
|
||||
* Never split or parsed here — that belongs to the resolution seam
|
||||
* (ADR-3646), not this grammar layer. Null for a checkpoint task (never
|
||||
* read), an absent attribute, or an empty-string value (`tracker-id=""`
|
||||
* normalises to null, same as every other optional attribute here).
|
||||
*/
|
||||
trackerId: string | null;
|
||||
}
|
||||
|
||||
interface PlanDocument {
|
||||
@@ -196,6 +205,7 @@ function parseXmlTasks(content: string): PlanTask[] {
|
||||
plannedFiles: [],
|
||||
acceptanceCriteria: [],
|
||||
done: null,
|
||||
trackerId: null,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -207,6 +217,7 @@ function parseXmlTasks(content: string): PlanTask[] {
|
||||
plannedFiles: splitFileList(elementBody(block, 'files')),
|
||||
acceptanceCriteria: splitCriteria(elementBody(block, 'acceptance_criteria')),
|
||||
done: collapseWhitespace(elementBody(block, 'done')),
|
||||
trackerId: tagAttribute(openTag, 'tracker-id'),
|
||||
};
|
||||
});
|
||||
}
|
||||
@@ -225,6 +236,7 @@ function parseMarkdownTasks(content: string): PlanTask[] {
|
||||
plannedFiles: [],
|
||||
acceptanceCriteria: [],
|
||||
done: null,
|
||||
trackerId: null,
|
||||
}));
|
||||
}
|
||||
|
||||
|
||||
@@ -11,6 +11,20 @@ import path from 'node:path';
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import ioMod = require('./io.cjs');
|
||||
const { output, error, ERROR_REASON } = ioMod;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import planDocumentMod = require('./plan-document.cjs');
|
||||
const { parsePlanDocument } = planDocumentMod;
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import capabilityLoaderMod = require('./capability-loader.cjs');
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import taskContentResolutionMod = require('./task-content-resolution.cjs');
|
||||
const {
|
||||
resolveTaskContent,
|
||||
ResolverAmbiguousError,
|
||||
ResolverFailedError,
|
||||
ResolverTimeoutError,
|
||||
ResolverMalformedOutputError,
|
||||
} = taskContentResolutionMod;
|
||||
|
||||
// ─── Types ────────────────────────────────────────────────────────────────────
|
||||
|
||||
@@ -32,6 +46,26 @@ interface RouteTaskCommandOptions {
|
||||
raw: boolean;
|
||||
}
|
||||
|
||||
interface PlanTaskLike {
|
||||
trackerId: string | null;
|
||||
}
|
||||
|
||||
interface CapabilityLike {
|
||||
id: string;
|
||||
taskContentResolver?: unknown;
|
||||
}
|
||||
|
||||
/**
|
||||
* Testability seam for `routeResolveContent` (mirrors this codebase's other
|
||||
* routers' `_`-prefixed injection convention, e.g.
|
||||
* `refactor-trigger-command-router.cts`'s `_git`/`_windows`/`_core`).
|
||||
* Production callers omit both fields.
|
||||
*/
|
||||
interface ResolveContentDeps {
|
||||
loadCapabilities?: (cwd: string) => CapabilityLike[];
|
||||
resolveTaskContentFn?: typeof resolveTaskContent;
|
||||
}
|
||||
|
||||
// ─── Implementation ───────────────────────────────────────────────────────────
|
||||
|
||||
function isBehaviorAddingTaskContent(content: string): BehaviorAddingResult {
|
||||
@@ -75,10 +109,127 @@ function isBehaviorAddingTaskContent(content: string): BehaviorAddingResult {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Default (production) capability loader for `resolve-content`: the merged
|
||||
* first-party + validated-installed-overlay registry (ADR-1244 D2), the
|
||||
* established runtime read path for "installed capabilities including
|
||||
* third-party" — as opposed to `capability-loader.cts`'s heavier build-time
|
||||
* validation entry points or the static `capability-registry.cjs` alone
|
||||
* (first-party only, would miss a third-party capability's
|
||||
* `taskContentResolver` declaration entirely).
|
||||
*/
|
||||
function defaultLoadCapabilities(cwd: string): CapabilityLike[] {
|
||||
const registry = capabilityLoaderMod.loadRegistry({ includeInstalled: true, cwd }) as {
|
||||
capabilities?: Record<string, CapabilityLike>;
|
||||
};
|
||||
return Object.values(registry.capabilities ?? {});
|
||||
}
|
||||
|
||||
function parseResolveContentArgs(args: string[]): { plan: string | null; taskId: string | null } {
|
||||
let plan: string | null = null;
|
||||
let taskId: string | null = null;
|
||||
for (let i = 2; i < args.length; i++) {
|
||||
if (args[i] === '--plan') {
|
||||
plan = args[i + 1] ?? null;
|
||||
i++;
|
||||
} else if (args[i] === '--task-id') {
|
||||
taskId = args[i + 1] ?? null;
|
||||
i++;
|
||||
}
|
||||
}
|
||||
return { plan, taskId };
|
||||
}
|
||||
|
||||
/**
|
||||
* `task resolve-content --plan <PLAN.md path> --task-id <tracker-id value> --raw`
|
||||
* (ADR-3646 Decision 2). Resolves one task's content from the external
|
||||
* tracker its `tracker-id` attribute names, via `task-content-resolution.cts`.
|
||||
*
|
||||
* HARD-HALT CONTRACT: a thrown `ResolverAmbiguousError` / `ResolverFailedError`
|
||||
* / `ResolverTimeoutError` / `ResolverMalformedOutputError` from
|
||||
* `resolveTaskContent` is turned into this CLI's own non-zero exit via
|
||||
* `error()` — never swallowed into a `{resolved: false}` JSON answer. Any
|
||||
* other thrown error is not one of the four documented resolver-error
|
||||
* classes and is allowed to propagate uncaught.
|
||||
*/
|
||||
function routeResolveContent(
|
||||
{ args, cwd, raw }: RouteTaskCommandOptions,
|
||||
deps: ResolveContentDeps = {},
|
||||
): void {
|
||||
const usage = 'Usage: task resolve-content --plan <path> --task-id <tracker-id> --raw';
|
||||
const { plan, taskId } = parseResolveContentArgs(args);
|
||||
if (!plan || !taskId) {
|
||||
error(usage, ERROR_REASON.USAGE);
|
||||
return;
|
||||
}
|
||||
|
||||
const projectRoot = path.resolve(cwd || process.cwd());
|
||||
const resolvedPlanPath = path.resolve(projectRoot, plan);
|
||||
const rel = path.relative(projectRoot, resolvedPlanPath);
|
||||
if (rel === '..' || rel.startsWith(`..${path.sep}`)) {
|
||||
error(`Plan file is outside project scope: ${plan}`, ERROR_REASON.USAGE);
|
||||
return;
|
||||
}
|
||||
if (!fs.existsSync(resolvedPlanPath)) {
|
||||
error(`Plan file not found: ${plan}`, ERROR_REASON.USAGE);
|
||||
return;
|
||||
}
|
||||
|
||||
const planContent = fs.readFileSync(resolvedPlanPath, 'utf-8');
|
||||
const parsedPlan = parsePlanDocument(planContent, resolvedPlanPath) as { tasks?: PlanTaskLike[] };
|
||||
const task = (parsedPlan.tasks ?? []).find((t) => t.trackerId === taskId);
|
||||
if (!task) {
|
||||
error(`No task with tracker-id '${taskId}' found in plan: ${plan}`, ERROR_REASON.USAGE);
|
||||
return;
|
||||
}
|
||||
|
||||
const loadCapabilities = deps.loadCapabilities ?? defaultLoadCapabilities;
|
||||
const capabilities = loadCapabilities(projectRoot);
|
||||
const resolveFn = deps.resolveTaskContentFn ?? resolveTaskContent;
|
||||
|
||||
let result;
|
||||
try {
|
||||
result = resolveFn({ trackerId: task.trackerId, capabilities });
|
||||
} catch (err) {
|
||||
if (
|
||||
err instanceof ResolverAmbiguousError ||
|
||||
err instanceof ResolverFailedError ||
|
||||
err instanceof ResolverTimeoutError ||
|
||||
err instanceof ResolverMalformedOutputError
|
||||
) {
|
||||
error((err as Error).message, ERROR_REASON.UNKNOWN);
|
||||
return;
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
|
||||
switch (result.kind) {
|
||||
case 'not-applicable':
|
||||
output({ resolved: false }, raw, undefined);
|
||||
return;
|
||||
case 'no-resolver':
|
||||
output({ resolved: false, reason: 'no-resolver' }, raw, undefined);
|
||||
return;
|
||||
case 'empty':
|
||||
output({ resolved: false, reason: 'empty' }, raw, undefined);
|
||||
return;
|
||||
case 'resolved':
|
||||
output({ resolved: true, content: result.content }, raw, undefined);
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
function routeTaskCommand({ args, cwd, raw }: RouteTaskCommandOptions): void {
|
||||
const subcommand = args[1];
|
||||
if (subcommand === 'resolve-content') {
|
||||
routeResolveContent({ args, cwd, raw });
|
||||
return;
|
||||
}
|
||||
if (subcommand !== 'is-behavior-adding') {
|
||||
error('Unknown task subcommand. Available: is-behavior-adding', ERROR_REASON.SDK_UNKNOWN_COMMAND);
|
||||
error(
|
||||
'Unknown task subcommand. Available: is-behavior-adding, resolve-content',
|
||||
ERROR_REASON.SDK_UNKNOWN_COMMAND,
|
||||
);
|
||||
}
|
||||
|
||||
let content: string | null = null;
|
||||
@@ -108,4 +259,5 @@ function routeTaskCommand({ args, cwd, raw }: RouteTaskCommandOptions): void {
|
||||
export = {
|
||||
isBehaviorAddingTaskContent,
|
||||
routeTaskCommand,
|
||||
routeResolveContent,
|
||||
};
|
||||
|
||||
475
src/task-content-resolution.cts
Normal file
475
src/task-content-resolution.cts
Normal file
@@ -0,0 +1,475 @@
|
||||
/**
|
||||
* Task Content Resolution Module (ADR-3646 Phase 1, #3970).
|
||||
*
|
||||
* Given a task's `tracker-id` attribute value (parsed verbatim by
|
||||
* `plan-document.cts`, never split there) and the set of installed
|
||||
* capabilities' `taskContentResolver` declarations, resolves the task's
|
||||
* content from the matching external tracker via a bounded subprocess call —
|
||||
* or reports that no resolution applies.
|
||||
*
|
||||
* PURE / IMPURE SPLIT, loosely mirroring `review-lane-invocation.cts`'s
|
||||
* resolve-then-run shape, but deliberately NOT copying its full machinery
|
||||
* (Gall's Law — see `40-design.md`'s "Laws that apply" section): this problem
|
||||
* has no probe/model/effort/prompt-channel axes, just one deterministic
|
||||
* id-lookup. `splitTrackerId`, `findResolver`, and `buildInvocation` are pure
|
||||
* and total (never throw, even on hostile third-party-shaped input — a
|
||||
* capability manifest is third-party-authored, and while `capability-
|
||||
* validator.cjs` validates it at install time, this module re-validates
|
||||
* defensively rather than trusting that boundary). `resolveTaskContent` is
|
||||
* the one impure boundary: it spawns exactly one bounded subprocess, through
|
||||
* an injectable `execFn` so tests never spawn a real process or wait a real
|
||||
* timeout (CLAUDE.md's clock-seam rule).
|
||||
*
|
||||
* HARD-HALT CONTRACT (ADR-3646 Decision 4): an ambiguous resolver match, a
|
||||
* non-zero resolver exit, a timeout, or malformed resolver stdout all THROW.
|
||||
* None of these degrade to a silently-empty or silently-picked result — a
|
||||
* task-content resolution failure must halt the caller (`task-command-
|
||||
* router.cts`'s `resolve-content` subcommand turns each throw into the CLI's
|
||||
* own non-zero exit), never fall back to inline PLAN.md content pretending
|
||||
* nothing happened.
|
||||
*
|
||||
* ADR-457 build-at-publish: source in src/task-content-resolution.cts,
|
||||
* compiled to gsd-core/bin/lib/task-content-resolution.cjs (gitignored).
|
||||
*/
|
||||
|
||||
// Use non-destructured namespace import so test-time mock.method(childProcess,
|
||||
// 'spawnSync') can intercept calls from this seam — destructured imports
|
||||
// capture references at load time and become un-mockable (matches the
|
||||
// convention documented in shell-command-projection.cts).
|
||||
import childProcess from 'node:child_process';
|
||||
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
||||
import ioMod = require('./io.cjs');
|
||||
const { formatDiagnosticToken } = ioMod;
|
||||
|
||||
// ─── Result taxonomy ──────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* The four non-throwing outcomes of `resolveTaskContent`. Frozen because the
|
||||
* `kind` discriminant is the product — callers (the CLI seam) switch on it
|
||||
* directly rather than string-matching prose.
|
||||
*/
|
||||
const TASK_CONTENT_RESULT = Object.freeze({
|
||||
NOT_APPLICABLE: 'not-applicable',
|
||||
NO_RESOLVER: 'no-resolver',
|
||||
RESOLVED: 'resolved',
|
||||
EMPTY: 'empty',
|
||||
} as const);
|
||||
|
||||
type TaskContentResultKind =
|
||||
(typeof TASK_CONTENT_RESULT)[keyof typeof TASK_CONTENT_RESULT];
|
||||
|
||||
interface ResolvedTaskContent {
|
||||
action: string | null;
|
||||
verify: string | null;
|
||||
acceptanceCriteria: string[];
|
||||
readFirst: string[];
|
||||
done: string | null;
|
||||
}
|
||||
|
||||
type TaskContentResolution =
|
||||
| { kind: 'not-applicable' }
|
||||
| { kind: 'no-resolver' }
|
||||
| { kind: 'empty' }
|
||||
| { kind: 'resolved'; content: ResolvedTaskContent };
|
||||
|
||||
// ─── Throwable error taxonomy ─────────────────────────────────────────────────
|
||||
// These four ALWAYS throw — they are configuration/execution defects, never a
|
||||
// value `resolveTaskContent` returns. See the module docstring's hard-halt
|
||||
// contract.
|
||||
|
||||
/**
|
||||
* Two or more installed capabilities declare a `taskContentResolver` for the
|
||||
* same `trackerPrefix`. Structurally impossible in a correctly-validated
|
||||
* install (`capability-validator.cjs` enforces cross-capability prefix
|
||||
* uniqueness), but `findResolver` must still refuse to silently pick one if a
|
||||
* test harness or a validator bug ever produces this shape.
|
||||
*/
|
||||
class ResolverAmbiguousError extends Error {
|
||||
prefix: string;
|
||||
capabilityIds: string[];
|
||||
constructor(prefix: string, capabilityIds: string[]) {
|
||||
super(
|
||||
`tracker prefix '${prefix}' matches ${capabilityIds.length} installed capability resolvers ` +
|
||||
`(${capabilityIds.join(', ')}) — ambiguous resolver registration must never silently pick one`,
|
||||
);
|
||||
this.name = 'ResolverAmbiguousError';
|
||||
this.prefix = prefix;
|
||||
this.capabilityIds = capabilityIds;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The resolver subprocess exited non-zero (or failed to spawn at all).
|
||||
*
|
||||
* `stderrTail` is UNTRUSTED subprocess-sourced text (the resolver binary is
|
||||
* declared by a capability manifest and invoked with an argv token derived
|
||||
* from a PLAN.md `tracker-id` attribute, which is often LLM/agent-authored —
|
||||
* a hostile or buggy resolver could echo attacker-influenced text back on
|
||||
* its own stderr). `.message` embeds it through `io.cjs`'s
|
||||
* `formatDiagnosticToken()` so every caller of `resolveTaskContent` gets a
|
||||
* `.message` that is already safe to write verbatim to a plain-text
|
||||
* diagnostic — see that function's docstring for why this must happen here,
|
||||
* at the point the untrusted substring is embedded, rather than at each
|
||||
* call site.
|
||||
*/
|
||||
class ResolverFailedError extends Error {
|
||||
exitCode: number | null;
|
||||
stderrTail: string;
|
||||
constructor(binary: string, exitCode: number | null, stderrTail: string) {
|
||||
super(
|
||||
`resolver command '${binary}' exited ${exitCode === null ? 'with no exit code (spawn failure)' : exitCode}` +
|
||||
(stderrTail ? `: ${formatDiagnosticToken(stderrTail)}` : ''),
|
||||
);
|
||||
this.name = 'ResolverFailedError';
|
||||
this.exitCode = exitCode;
|
||||
this.stderrTail = stderrTail;
|
||||
}
|
||||
}
|
||||
|
||||
/** The resolver subprocess exceeded its declared `invoke.timeoutMs` bound. */
|
||||
class ResolverTimeoutError extends Error {
|
||||
timeoutMs: number;
|
||||
constructor(binary: string, timeoutMs: number) {
|
||||
super(`resolver command '${binary}' timed out after ${timeoutMs}ms`);
|
||||
this.name = 'ResolverTimeoutError';
|
||||
this.timeoutMs = timeoutMs;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The resolver's stdout was not valid JSON, or was valid JSON that is not a
|
||||
* plain object (a `null`, array, string, number, or boolean top-level value
|
||||
* is rejected — only a plain object can carry the `description`/`verify`/
|
||||
* `acceptance_criteria`/`read_first`/`done` fields this seam reads).
|
||||
*/
|
||||
class ResolverMalformedOutputError extends Error {
|
||||
stdoutSample: string;
|
||||
constructor(binary: string, reason: string, stdoutSample: string) {
|
||||
super(
|
||||
`resolver command '${binary}' produced malformed output: ${reason}` +
|
||||
(stdoutSample ? ` (stdout sample: ${formatDiagnosticToken(stdoutSample)})` : ''),
|
||||
);
|
||||
this.name = 'ResolverMalformedOutputError';
|
||||
this.stdoutSample = stdoutSample;
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Manifest shapes ───────────────────────────────────────────────────────────
|
||||
|
||||
interface TaskContentResolverInvoke {
|
||||
binary: string;
|
||||
args: string[];
|
||||
timeoutMs: number;
|
||||
}
|
||||
|
||||
interface TaskContentResolverDeclaration {
|
||||
capabilityId: string;
|
||||
trackerPrefix: string;
|
||||
invoke: TaskContentResolverInvoke;
|
||||
}
|
||||
|
||||
interface CapabilityLike {
|
||||
id: string;
|
||||
taskContentResolver?: unknown;
|
||||
}
|
||||
|
||||
// ─── Pure functions ────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* The SAME kebab-case grammar `capability-validator.cjs`'s `KEBAB_RE`
|
||||
* enforces on `taskContentResolver.trackerPrefix` at install time
|
||||
* (`validateTaskContentResolverFields`). Duplicated as a literal rather than
|
||||
* imported — `.cts` (build-at-publish, ADR-457) and the hand-written
|
||||
* `capability-validator.cjs` are genuinely two different build targets with
|
||||
* no shared-constants module between them today — but `tests/task-content-
|
||||
* resolver-grammar-parity.test.cjs` asserts both regexes agree on a shared
|
||||
* table of inputs, so a future edit to either one that silently diverges from
|
||||
* the other fails a test instead of drifting quietly (CLAUDE.md's Generative
|
||||
* Fix Divergence rule).
|
||||
*/
|
||||
const TRACKER_PREFIX_RE = /^[a-z][a-z0-9-]*$/;
|
||||
|
||||
/**
|
||||
* Split a `tracker-id` attribute value into its prefix and id, on the FIRST
|
||||
* `:` only — colons after the first stay in the id verbatim (a tracker whose
|
||||
* native ids contain colons, e.g. `beads:issue:GSD-1` → `{prefix: "beads",
|
||||
* id: "issue:GSD-1"}`).
|
||||
*
|
||||
* PURE. Returns `null` for `null`/empty input, and for a string with no `:`
|
||||
* at all (nothing to split — there is no prefix to match a resolver against).
|
||||
*/
|
||||
function splitTrackerId(trackerId: string | null): { prefix: string; id: string } | null {
|
||||
if (typeof trackerId !== 'string' || trackerId.length === 0) return null;
|
||||
const colonIdx = trackerId.indexOf(':');
|
||||
if (colonIdx === -1) return null;
|
||||
const prefix = trackerId.slice(0, colonIdx);
|
||||
const id = trackerId.slice(colonIdx + 1);
|
||||
if (!prefix || !id) return null;
|
||||
return { prefix, id };
|
||||
}
|
||||
|
||||
/**
|
||||
* Defensively re-validate a raw `taskContentResolver` declaration's shape.
|
||||
* `capability-validator.cjs` already enforces this at install time, but this
|
||||
* module treats every capability manifest as third-party-authored input and
|
||||
* never trusts a shape it has not itself checked — a malformed declaration is
|
||||
* treated as though it does not exist for matching purposes, never thrown on.
|
||||
*/
|
||||
function parseResolverDeclaration(
|
||||
capabilityId: string,
|
||||
raw: unknown,
|
||||
): TaskContentResolverDeclaration | null {
|
||||
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
|
||||
const body = raw as { trackerPrefix?: unknown; invoke?: unknown };
|
||||
const trackerPrefix = typeof body.trackerPrefix === 'string' ? body.trackerPrefix.trim() : '';
|
||||
if (!trackerPrefix || !TRACKER_PREFIX_RE.test(trackerPrefix)) return null;
|
||||
|
||||
const inv = body.invoke;
|
||||
if (inv === null || typeof inv !== 'object' || Array.isArray(inv)) return null;
|
||||
const invBody = inv as { binary?: unknown; args?: unknown; timeoutMs?: unknown };
|
||||
|
||||
const binary = typeof invBody.binary === 'string' ? invBody.binary.trim() : '';
|
||||
if (!binary) return null;
|
||||
|
||||
const args = Array.isArray(invBody.args)
|
||||
? invBody.args.filter((a): a is string => typeof a === 'string')
|
||||
: null;
|
||||
if (args === null || args.length !== (invBody.args as unknown[]).length) return null;
|
||||
if (!args.includes('{{id}}')) return null;
|
||||
|
||||
const timeoutMs = invBody.timeoutMs;
|
||||
if (typeof timeoutMs !== 'number' || !Number.isInteger(timeoutMs) || timeoutMs <= 0) return null;
|
||||
|
||||
return {
|
||||
capabilityId,
|
||||
trackerPrefix,
|
||||
invoke: { binary, args, timeoutMs },
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Find the resolver declared for `prefix` among `capabilities`.
|
||||
*
|
||||
* PURE, total. Returns:
|
||||
* - the single matching declaration when exactly one well-formed resolver
|
||||
* declares `trackerPrefix === prefix`;
|
||||
* - `null` when zero capabilities declare a well-formed resolver for it
|
||||
* (an unrecognized prefix is a data case, not a defect — see design row 11);
|
||||
* - the literal string `'ambiguous'` when two or more do — this must be
|
||||
* structurally impossible in a correctly-validated install, but this
|
||||
* function refuses to silently pick one regardless.
|
||||
*/
|
||||
function findResolver(
|
||||
prefix: string,
|
||||
capabilities: Array<CapabilityLike>,
|
||||
): TaskContentResolverDeclaration | 'ambiguous' | null {
|
||||
const matches: TaskContentResolverDeclaration[] = [];
|
||||
for (const cap of capabilities ?? []) {
|
||||
if (!cap || typeof cap !== 'object') continue;
|
||||
const decl = parseResolverDeclaration(cap.id, cap.taskContentResolver);
|
||||
if (decl && decl.trackerPrefix === prefix) matches.push(decl);
|
||||
}
|
||||
if (matches.length === 0) return null;
|
||||
if (matches.length > 1) return 'ambiguous';
|
||||
return matches[0];
|
||||
}
|
||||
|
||||
/**
|
||||
* Expand a resolver's `invoke.args` template, replacing every `"{{id}}"`
|
||||
* entry with the literal `id` string. Exact-match token replacement, not
|
||||
* template-string interpolation — mirrors `review-lane-invocation.cts`'s
|
||||
* argv-expansion discipline (a placeholder is a whole array element, not a
|
||||
* substring).
|
||||
*
|
||||
* PURE.
|
||||
*/
|
||||
function buildInvocation(
|
||||
resolver: { invoke: TaskContentResolverInvoke },
|
||||
id: string,
|
||||
): TaskContentResolverInvoke {
|
||||
return {
|
||||
binary: resolver.invoke.binary,
|
||||
args: resolver.invoke.args.map((a) => (a === '{{id}}' ? id : a)),
|
||||
timeoutMs: resolver.invoke.timeoutMs,
|
||||
};
|
||||
}
|
||||
|
||||
// ─── Subprocess boundary ──────────────────────────────────────────────────────
|
||||
|
||||
interface ExecResult {
|
||||
status: number | null;
|
||||
stdout: string;
|
||||
stderr: string;
|
||||
error?: Error;
|
||||
}
|
||||
|
||||
type ExecFn = (binary: string, args: string[], opts: { timeout: number }) => ExecResult;
|
||||
|
||||
/**
|
||||
* Real subprocess execution — the default `execFn`. Uses Node's `spawnSync`
|
||||
* with the `timeout` option so a hung resolver is killed at the bound rather
|
||||
* than hanging the caller (CLAUDE.md's Unbounded Subprocesses gauntlet line).
|
||||
*/
|
||||
function realExec(binary: string, args: string[], opts: { timeout: number }): ExecResult {
|
||||
const result = childProcess.spawnSync(binary, args, {
|
||||
encoding: 'utf-8',
|
||||
stdio: 'pipe',
|
||||
timeout: opts.timeout,
|
||||
windowsHide: true,
|
||||
});
|
||||
return {
|
||||
status: result.status ?? null,
|
||||
stdout: (result.stdout ?? '').toString(),
|
||||
stderr: (result.stderr ?? '').toString(),
|
||||
error: result.error ?? undefined,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* True when an `ExecResult` indicates the subprocess was killed by the
|
||||
* `timeout` option, i.e. it never completed and reported a real answer. Only
|
||||
* `error.code === 'ETIMEDOUT'` is checked — Node.js guarantees this
|
||||
* cross-platform when `spawnSync`'s `timeout` option fires; pairing it with a
|
||||
* `signal === 'SIGTERM'` check is platform-fragile (Windows does not
|
||||
* necessarily report SIGTERM the same way) and risks a false negative. Same
|
||||
* predicate discipline as `shell-command-projection.cts`'s `isSpawnTimeout`.
|
||||
*/
|
||||
function isExecTimeout(result: ExecResult): boolean {
|
||||
const err: NodeJS.ErrnoException | undefined = result.error;
|
||||
return err?.code === 'ETIMEDOUT';
|
||||
}
|
||||
|
||||
// ─── Resolver JSON → content mapping ──────────────────────────────────────────
|
||||
|
||||
function coerceStringOrNull(value: unknown): string | null {
|
||||
return typeof value === 'string' ? value : null;
|
||||
}
|
||||
|
||||
function coerceStringArray(value: unknown): string[] {
|
||||
return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Map a resolver's validated JSON object onto `ResolvedTaskContent`. Every
|
||||
* field is coerced defensively — the resolver's JSON is a third-party CLI's
|
||||
* output, validated for exit code and JSON-object-shape upstream, but never
|
||||
* trusted field-by-field. A missing or wrong-typed field degrades sanely
|
||||
* (string/null fields fall back to `null`, array fields fall back to `[]`);
|
||||
* only the caller's `description`-emptiness check throws no further errors
|
||||
* here — this function is never the one that decides `resolved` vs `empty`.
|
||||
*/
|
||||
function mapResolverOutput(body: Record<string, unknown>): ResolvedTaskContent {
|
||||
return {
|
||||
action: coerceStringOrNull(body['description']),
|
||||
verify: coerceStringOrNull(body['verify']),
|
||||
acceptanceCriteria: coerceStringArray(body['acceptance_criteria']),
|
||||
readFirst: coerceStringArray(body['read_first']),
|
||||
done: coerceStringOrNull(body['done']),
|
||||
};
|
||||
}
|
||||
|
||||
// ─── Entry point ────────────────────────────────────────────────────────────────
|
||||
|
||||
interface ResolveTaskContentInput {
|
||||
trackerId: string | null;
|
||||
capabilities: Array<CapabilityLike>;
|
||||
/** Override the resolver's declared `invoke.timeoutMs`, primarily for tests. */
|
||||
timeoutOverrideMs?: number;
|
||||
execFn?: ExecFn;
|
||||
}
|
||||
|
||||
/**
|
||||
* Orchestrate one task's content resolution: split the `tracker-id`, find the
|
||||
* matching capability's resolver, invoke it through the bounded subprocess
|
||||
* boundary, and map its JSON output onto the four documented outcomes.
|
||||
*
|
||||
* The only impure boundary is `execFn` (defaults to a real `spawnSync` call).
|
||||
* Injecting a fake `execFn` lets tests assert every outcome — including a
|
||||
* timeout — deterministically, without spawning a real process or waiting a
|
||||
* real `timeoutMs`.
|
||||
*/
|
||||
function resolveTaskContent(input: ResolveTaskContentInput): TaskContentResolution {
|
||||
const split = splitTrackerId(input.trackerId);
|
||||
if (split === null) return { kind: TASK_CONTENT_RESULT.NOT_APPLICABLE };
|
||||
|
||||
const resolver = findResolver(split.prefix, input.capabilities ?? []);
|
||||
if (resolver === null) return { kind: TASK_CONTENT_RESULT.NO_RESOLVER };
|
||||
if (resolver === 'ambiguous') {
|
||||
// findResolver never returns the capability ids for the ambiguous case
|
||||
// (it discards the losing matches) — re-derive them here for the error.
|
||||
const ids = (input.capabilities ?? [])
|
||||
.filter((cap) => {
|
||||
const decl = parseResolverDeclaration(cap?.id, cap?.taskContentResolver);
|
||||
return decl !== null && decl.trackerPrefix === split.prefix;
|
||||
})
|
||||
.map((cap) => cap.id);
|
||||
throw new ResolverAmbiguousError(split.prefix, ids);
|
||||
}
|
||||
|
||||
const invocation = buildInvocation(resolver, split.id);
|
||||
const timeoutMs = input.timeoutOverrideMs ?? invocation.timeoutMs;
|
||||
const execFn = input.execFn ?? realExec;
|
||||
const result = execFn(invocation.binary, invocation.args, { timeout: timeoutMs });
|
||||
|
||||
if (isExecTimeout(result)) {
|
||||
throw new ResolverTimeoutError(invocation.binary, timeoutMs);
|
||||
}
|
||||
if (result.error || result.status !== 0) {
|
||||
const stderrTail = (result.stderr ?? '').trim().slice(-2000);
|
||||
throw new ResolverFailedError(invocation.binary, result.status, stderrTail);
|
||||
}
|
||||
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(result.stdout);
|
||||
} catch {
|
||||
throw new ResolverMalformedOutputError(
|
||||
invocation.binary,
|
||||
'stdout is not valid JSON',
|
||||
result.stdout.slice(0, 200),
|
||||
);
|
||||
}
|
||||
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
|
||||
throw new ResolverMalformedOutputError(
|
||||
invocation.binary,
|
||||
`stdout parsed as valid JSON but is not a plain object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`,
|
||||
result.stdout.slice(0, 200),
|
||||
);
|
||||
}
|
||||
|
||||
const content = mapResolverOutput(parsed as Record<string, unknown>);
|
||||
const description = typeof content.action === 'string' ? content.action.trim() : '';
|
||||
if (description.length === 0) {
|
||||
return { kind: TASK_CONTENT_RESULT.EMPTY };
|
||||
}
|
||||
return { kind: TASK_CONTENT_RESULT.RESOLVED, content };
|
||||
}
|
||||
|
||||
const taskContentResolution = {
|
||||
TASK_CONTENT_RESULT,
|
||||
splitTrackerId,
|
||||
findResolver,
|
||||
buildInvocation,
|
||||
resolveTaskContent,
|
||||
ResolverAmbiguousError,
|
||||
ResolverFailedError,
|
||||
ResolverTimeoutError,
|
||||
ResolverMalformedOutputError,
|
||||
};
|
||||
|
||||
// eslint-disable-next-line @typescript-eslint/no-namespace
|
||||
declare namespace taskContentResolution {
|
||||
export {
|
||||
TaskContentResultKind,
|
||||
ResolvedTaskContent,
|
||||
TaskContentResolution,
|
||||
TaskContentResolverInvoke,
|
||||
TaskContentResolverDeclaration,
|
||||
CapabilityLike,
|
||||
ExecResult,
|
||||
ExecFn,
|
||||
ResolveTaskContentInput,
|
||||
};
|
||||
}
|
||||
|
||||
export = taskContentResolution;
|
||||
Reference in New Issue
Block a user