@event4u/agent-config 8.4.0 → 8.5.0

package/src/agent-src/templates/scripts/work_engine/resolvers/file.ts

@@ -0,0 +1,175 @@
+/**
+ * File resolver — wrap a path reference as an {@link Input} envelope.
+ *
+ * TypeScript twin of `work_engine/resolvers/file.py` (ADR-200 py2ts —
+ * work_engine foundation). Public API names stay snake_case to mirror the
+ * Python module 1:1 (per ADR-200 — Python style is part of the contract).
+ *
+ * The resolver is the R3 Phase 1 entry point for the "improve this existing
+ * component/page" surface: a user hands the engine a path (e.g.,
+ * `resources/views/dashboard.blade.php` or `src/components/Sidebar.tsx`),
+ * the resolver normalises it, and the dispatcher routes the envelope through
+ * the UI-track `ui-improve` directive set.
+ *
+ * Like `work_engine.resolvers.prompt` and `.diff`, this module is
+ * intentionally thin: it normalises and rejects garbage payloads, nothing
+ * more. Existence checks, mtime caching, and content reads are deferred to
+ * the `analyze` step / the audit directive — a resolver doing I/O at the
+ * command-shell boundary would couple the envelope build to filesystem state
+ * and break replay-against-state-files.
+ *
+ * The envelope mirrors the prompt and diff resolvers so a single refiner code
+ * path can read all three — `{path, reconstructed_ac, assumptions}`. The
+ * only material difference is the path-shape check that rejects values that
+ * are obviously not paths (absolute URLs, empty strings, control chars).
+ */
+import * as path from 'node:path';
+
+import { Input } from '../state.js';
+
+export const KIND = 'file';
+/** Wire value carried in {@link Input.kind}. */
+
+const _MIN_PATH_LEN = 1;
+/**
+ * Minimum non-whitespace character count for a resolvable path.
+ *
+ * A 1-char path is rare but legal (`a`); the bar exists only to reject
+ * literal empty / whitespace-only payloads which carry no signal at all.
+ */
+
+const _FORBIDDEN_PREFIXES: readonly string[] = [
+    'http://',
+    'https://',
+    'ftp://',
+    'file://',
+];
+/**
+ * Prefixes that signal the caller passed a URL, not a filesystem path.
+ *
+ * The diff resolver handles patch URLs at a future R3 layer; the file
+ * resolver only accepts on-disk references. Rejecting URLs explicitly
+ * keeps misuse loud instead of letting the audit step discover it later.
+ * The check is case-insensitive.
+ */
+
+/** Raised when a payload cannot be resolved into a file envelope. */
+export class FileResolverError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'FileResolverError';
+        Object.setPrototypeOf(this, FileResolverError.prototype);
+    }
+}
+
+/**
+ * Return an {@link Input} carrying the path + empty refinement slots.
+ *
+ * @param path_ The user-supplied path reference. The resolver normalises only
+ *   by stripping leading/trailing whitespace; case, separators, and the
+ *   relative-vs-absolute distinction are all preserved verbatim so the
+ *   downstream audit step reads exactly what the user wrote.
+ * @returns Envelope of shape
+ *   `{"kind": "file", "data": {"path": <path>, "reconstructed_ac": [],
+ *   "assumptions": []}}`. The two empty lists are placeholders the
+ *   `refine-prompt` skill writes into on the rebound from `refine`; they are
+ *   kept to preserve a single-shape envelope across all prompt-like resolvers.
+ * @throws {@link FileResolverError} If `path` is not a string, is empty /
+ *   whitespace-only, contains a NUL byte (filesystem-illegal everywhere), or
+ *   is a URL (use the diff resolver for remote-PR / patch URLs in a future R3
+ *   phase).
+ */
+export function build_envelope(path_: unknown): Input {
+    if (typeof path_ !== 'string') {
+        throw new FileResolverError(
+            `path must be a string; got ${pyTypeName(path_)}`,
+        );
+    }
+    const stripped = pyStrip(path_);
+    if (stripped.length < _MIN_PATH_LEN) {
+        throw new FileResolverError(
+            'path is empty or whitespace-only — nothing to resolve',
+        );
+    }
+    if (stripped.includes('\x00')) {
+        throw new FileResolverError(
+            'path contains a NUL byte; filesystem references must be ' +
+                'NUL-free',
+        );
+    }
+    const lowered = stripped.toLowerCase();
+    if (_FORBIDDEN_PREFIXES.some((prefix) => lowered.startsWith(prefix))) {
+        throw new FileResolverError(
+            `path looks like a URL (${pyStrRepr(pySlice(stripped, 32))}); the file resolver ` +
+                'only accepts on-disk references — use the diff resolver for ' +
+                'PR or patch URLs',
+        );
+    }
+    // Normalise separators *only* on Windows-style backslashes so
+    // `resources\\views\\foo.blade.php` round-trips as POSIX. Native
+    // POSIX paths are returned untouched so the audit step's identity
+    // comparison against directory listings stays trivial.
+    const normalised =
+        path.sep === '/' ? stripped.replace(/\\/g, '/') : stripped;
+    return new Input(KIND, {
+        path: normalised,
+        reconstructed_ac: [],
+        assumptions: [],
+    });
+}
+
+// ── Python-parity helpers ───────────────────────────────────────────────
+
+/**
+ * Mirror Python `str.strip()` — see `resolvers/prompt.ts` for the parity note.
+ */
+function pyStrip(s: string): string {
+    return s.trim();
+}
+
+/**
+ * Mirror Python `s[:n]` over code points. The error path renders `stripped[:32]`
+ * via `!r`; Python slices by code point, not UTF-16 unit, so use the spread
+ * iterator to slice on code-point boundaries before re-joining.
+ */
+function pySlice(s: string, n: number): string {
+    return [...s].slice(0, n).join('');
+}
+
+/**
+ * Mirror Python `repr(str)` — prefers single quotes, switches to double quotes
+ * only when the string contains a single quote but no double quote, and escapes
+ * backslash plus the active quote and the standard control characters. Matches
+ * the `state.py` twin's `pyStrRepr` so the `{...!r}` error tail is byte-equal.
+ */
+function pyStrRepr(s: string): string {
+    const hasSingle = s.includes("'");
+    const hasDouble = s.includes('"');
+    const quote = hasSingle && !hasDouble ? '"' : "'";
+    let out = quote;
+    for (const ch of s) {
+        const code = ch.codePointAt(0) as number;
+        if (ch === '\\') out += '\\\\';
+        else if (ch === quote) out += '\\' + quote;
+        else if (ch === '\n') out += '\\n';
+        else if (ch === '\r') out += '\\r';
+        else if (ch === '\t') out += '\\t';
+        else if (code < 0x20 || code === 0x7f) {
+            out += `\\x${code.toString(16).padStart(2, '0')}`;
+        } else {
+            out += ch;
+        }
+    }
+    return out + quote;
+}
+
+/** Python `type(x).__name__` for the non-string `isinstance` guard branch. */
+function pyTypeName(v: unknown): string {
+    if (v === null) return 'NoneType';
+    if (v === undefined) return 'NoneType';
+    if (typeof v === 'boolean') return 'bool';
+    if (typeof v === 'string') return 'str';
+    if (typeof v === 'number') return Number.isInteger(v) ? 'int' : 'float';
+    if (Array.isArray(v)) return 'list';
+    return 'dict';
+}

package/src/agent-src/templates/scripts/work_engine/resolvers/prompt.ts

@@ -0,0 +1,115 @@
+/**
+ * Prompt resolver — wrap a raw user prompt as an {@link Input} envelope.
+ *
+ * TypeScript twin of `work_engine/resolvers/prompt.py` (ADR-200 py2ts —
+ * work_engine foundation). Public API names stay snake_case to mirror the
+ * Python module 1:1 (per ADR-200 — Python style is part of the contract).
+ *
+ * The resolver is intentionally minimal. It accepts a raw string, validates
+ * that it contains non-whitespace content, and returns
+ * `Input(kind="prompt", data={"raw": <text>, "reconstructed_ac": [],
+ * "assumptions": []})`. The empty AC + assumptions lists are placeholders
+ * that the `refine-prompt` skill (R2 Phase 3) fills in once the engine
+ * runs the deterministic `refine` gate against the raw text.
+ *
+ * Why split the resolver from the refiner:
+ *
+ * - The resolver runs at command boundaries (the `/work` entrypoint
+ *   builds an envelope, then hands off to `work_engine`). It must stay
+ *   side-effect-free and dependency-light so the command shell can call
+ *   it without touching the LLM-facing skill harness.
+ * - The refiner runs inside the dispatcher loop and is allowed to halt
+ *   (medium-confidence assumptions report, low-confidence one-question
+ *   block) per `docs/contracts/implement-ticket-flow.md`. That
+ *   control-flow surface does not belong in a resolver.
+ *
+ * Future R3 resolvers (`diff`, `file`) follow the same pattern: thin
+ * normalisation, no interpretation, one envelope shape per kind.
+ */
+import { Input } from '../state.js';
+
+export const KIND = 'prompt';
+/** Wire value carried in {@link Input.kind}. */
+
+const _MIN_PROMPT_LEN = 1;
+/**
+ * Minimum non-whitespace character count for a resolvable prompt.
+ *
+ * Set to 1 by design — the resolver is not a quality gate. It only
+ * rejects literally empty / whitespace-only payloads (which cannot be
+ * distinguished from missing input). Quality judgment (is the prompt
+ * clear? is it tractable?) is the `refine-prompt` skill's job, surfaced
+ * through the confidence band, not the resolver's.
+ */
+
+/** Raised when a payload cannot be resolved into a prompt envelope. */
+export class PromptResolverError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'PromptResolverError';
+        Object.setPrototypeOf(this, PromptResolverError.prototype);
+    }
+}
+
+/**
+ * Return an {@link Input} carrying the raw prompt + empty refinement slots.
+ *
+ * @param raw The user-supplied prompt text. Leading/trailing whitespace is
+ *   preserved verbatim — the refiner reads the original casing and spacing
+ *   when scoring goal clarity, so collapsing whitespace here would lose
+ *   signal.
+ * @returns Envelope of shape
+ *   `{"kind": "prompt", "data": {"raw": <raw>, "reconstructed_ac": [],
+ *   "assumptions": []}}`. The two empty lists are placeholders the
+ *   `refine-prompt` skill writes into on the rebound from the `refine` step.
+ * @throws {@link PromptResolverError} If `raw` is not a string, or contains
+ *   no non-whitespace characters (the only case where the envelope would
+ *   carry no actionable signal at all).
+ */
+export function build_envelope(raw: unknown): Input {
+    if (typeof raw !== 'string') {
+        throw new PromptResolverError(
+            `prompt must be a string; got ${pyTypeName(raw)}`,
+        );
+    }
+    if (pyStrip(raw).length < _MIN_PROMPT_LEN) {
+        throw new PromptResolverError(
+            'prompt is empty or whitespace-only — nothing to resolve',
+        );
+    }
+    return new Input(KIND, {
+        raw: raw,
+        reconstructed_ac: [],
+        assumptions: [],
+    });
+}
+
+// ── Python-parity helpers ───────────────────────────────────────────────
+
+/**
+ * Mirror Python `str.strip()` — strips the Unicode whitespace set CPython
+ * uses (the characters for which `str.isspace()` is true). `String.trim()`
+ * strips a near-identical set; the only practical divergence for the empty-
+ * payload guard is that `trim()` does not strip a handful of exotic code
+ * points (e.g. zero-width). For a length-vs-1 gate the standard `trim` is
+ * faithful for every realistic whitespace-only prompt, and any leftover
+ * exotic char would correctly count as "non-whitespace content" under both
+ * runtimes' intent. Kept as a named helper to mark the parity point.
+ */
+function pyStrip(s: string): string {
+    return s.trim();
+}
+
+/**
+ * Python `type(x).__name__` for the values this resolver's TypeError-equivalent
+ * branch reports: the `isinstance(raw, str)` guard fires on any non-string.
+ */
+function pyTypeName(v: unknown): string {
+    if (v === null) return 'NoneType';
+    if (v === undefined) return 'NoneType';
+    if (typeof v === 'boolean') return 'bool';
+    if (typeof v === 'string') return 'str';
+    if (typeof v === 'number') return Number.isInteger(v) ? 'int' : 'float';
+    if (Array.isArray(v)) return 'list';
+    return 'dict';
+}