@planningo/duul 1.0.0

package/build/schemas/plan-review.js

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+import { ArtifactRefSchema, ReviewerConfigSchema, IterationMetaOutputSchema, TokenUsageOutputSchema } from './common.js';
+export const ProjectContextSchema = z.object({
+    file_tree: z
+        .string()
+        .max(2000, 'file_tree must be at most 2000 characters')
+        .optional()
+        .describe('Project file tree summary (top-level dirs + changed files only, max 2000 chars)'),
+    changed_files: z
+        .array(z.string())
+        .optional()
+        .describe('List of files related to this change'),
+    package_versions: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Key package versions, e.g. { "express": "4.18.2" }'),
+    relevant_code: z
+        .array(z.object({
+        file_path: z.string().describe('File path'),
+        code: z.string().describe('Relevant code snippet (types, interfaces, functions, classes)'),
+    }))
+        .optional()
+        .describe('Related code snippets the reviewer should see for full context. ' +
+        'Include type definitions, interfaces, data models, and surrounding code ' +
+        'that are relevant to the plan but not part of the change itself.'),
+});
+export const PlanReviewInputSchema = z.object({
+    plan: z.string().min(1, 'plan must not be empty').describe('Detailed implementation plan'),
+    project_context: ProjectContextSchema.optional().describe('Structured project context'),
+    constraints: z
+        .array(z.string())
+        .optional()
+        .describe('Special constraints: performance, memory, security, etc.'),
+    notes_to_reviewer: z
+        .string()
+        .optional()
+        .describe('Context or rebuttals from the caller to the reviewer. ' +
+        'Use this to explain codebase-specific facts the reviewer cannot see, ' +
+        'or to respond to blocking issues from a previous round.'),
+    user_original_request: z
+        .string()
+        .max(4000)
+        .optional()
+        .describe("The user's original, unedited problem statement (not paraphrased by the caller). " +
+        'Used by the reviewer to verify the plan actually addresses the reported symptom.'),
+    // --- Workspace-aware scope fields ---
+    workspace_root: z
+        .string()
+        .optional()
+        .describe('Absolute path to the workspace root directory. Preferred over project_root. ' +
+        'When provided, the reviewer gains file exploration tools scoped to this workspace.'),
+    project_root: z
+        .string()
+        .optional()
+        .describe('[DEPRECATED — use workspace_root] Absolute path to the project root directory. ' +
+        'Used as fallback when workspace_root is not provided.'),
+    working_directories: z
+        .array(z.string())
+        .optional()
+        .describe('Subdirectories within workspace_root to restrict file access to. ' +
+        'Acts as a sparse-checkout-like allowlist. If omitted, entire workspace_root is accessible.'),
+    linked_roots: z
+        .array(z.string())
+        .max(5)
+        .optional()
+        .describe('Additional read-only workspace roots the reviewer can access. ' +
+        'Each must be a valid absolute path (3+ depth). Max 5.'),
+    changed_files: z
+        .array(z.string())
+        .optional()
+        .describe('Files changed in this review scope (top-level, separate from project_context)'),
+    entrypoints: z
+        .array(z.string())
+        .optional()
+        .describe('Entry point files the reviewer should start from'),
+    artifact_refs: z
+        .array(ArtifactRefSchema)
+        .max(30)
+        .optional()
+        .describe('References to important files with reason and priority. Max 30.'),
+    tracked_only: z
+        .boolean()
+        .optional()
+        .describe('When true, only git-tracked files are accessible to the reviewer.'),
+    // --- Git metadata ---
+    git_head_sha: z.string().optional().describe('Current git HEAD SHA for this review'),
+    previous_git_head_sha: z.string().optional().describe('Git HEAD SHA from the previous review round. Used with git_head_sha to detect stale context.'),
+    workspace_name: z.string().optional().describe('Name of the workspace (for logging/identification)'),
+    // --- Setup/Run metadata ---
+    setup_script_present: z.boolean().optional().describe('Whether a setup script exists in the workspace'),
+    run_script_present: z.boolean().optional().describe('Whether a run/start script exists in the workspace'),
+    environment_files_expected: z.array(z.string()).optional().describe('Environment files expected but not tracked (e.g. [".env", ".env.local"]). Prevents false positives.'),
+    // --- Git diff ---
+    git_diff: z
+        .string()
+        .optional()
+        .describe('Pre-computed git diff to include in review context. If omitted and workspace_root + changed_files are provided, ' +
+        'the diff is auto-generated.'),
+    git_diff_base: z
+        .string()
+        .optional()
+        .describe('Base ref for auto-generated git diff (e.g. "HEAD", "main"). Default: "HEAD".'),
+    previous_review_id: z
+        .string()
+        .optional()
+        .describe('Response ID from a previous review call. Pass this to maintain reviewer context ' +
+        'across rounds — the reviewer will remember all files it read, previous feedback, ' +
+        'and the full conversation history.'),
+    // --- Iteration tracking ---
+    iteration_count: z
+        .number()
+        .min(1)
+        .optional()
+        .describe('Current iteration number (1-based). The caller MUST increment this on each call. ' +
+        'When this reaches the iteration limit, the server returns requires_human_review: true.'),
+    max_review_iterations: z
+        .number()
+        .min(1)
+        .max(20)
+        .optional()
+        .describe('Override the maximum iterations for this phase. Default: env MAX_PLAN_REVIEW_ITERATIONS or 7.'),
+    // --- Reviewer config ---
+    reviewer_config: ReviewerConfigSchema.optional().describe('Per-request reviewer configuration. Overrides env defaults.'),
+});
+const BlockingIssueSchema = z.object({
+    description: z.string().describe('What the issue is'),
+    suggestion: z.string().describe('How to fix it'),
+});
+export const PlanReviewOutputSchema = z.object({
+    verdict: z.enum(['APPROVE', 'REVISE']).describe('Final verdict'),
+    review_status: z.enum(['completed', 'incomplete']).describe('Whether the review was fully completed. "incomplete" means the tool loop was exhausted before the reviewer could finish.'),
+    confidence: z.number().min(0).max(1).describe('Confidence in the verdict (0-1), advisory only'),
+    requires_human_review: z.boolean().describe('Whether a human should review this'),
+    architectural_analysis: z.string().describe('Structural pros/cons analysis'),
+    blocking_issues: z
+        .array(BlockingIssueSchema)
+        .describe('Issues that must be fixed before proceeding'),
+    merge_blockers: z
+        .array(BlockingIssueSchema)
+        .nullable()
+        .describe('Subset of blocking_issues that should block merge. Null if same as blocking_issues.'),
+    non_blocking_suggestions: z
+        .array(z.string())
+        .describe('Optional improvement suggestions'),
+    edge_cases: z.array(z.string()).describe('Unconsidered edge cases'),
+    checklist_for_implementation: z
+        .array(z.string())
+        .describe('Must-follow checklist for implementation'),
+    follow_up_todos: z.array(z.string()).nullable().describe('Follow-up tasks after implementation'),
+    missing_context: z.array(z.string()).nullable().describe('Files or context the reviewer could not access'),
+    evidence_files: z.array(z.string()).nullable().describe('Files the reviewer examined as evidence'),
+    used_tools: z.array(z.string()).nullable().describe('Tool calls made during review'),
+    tool_exhaustion_reason: z.enum(['budget', 'repeat', 'round_limit']).nullable().describe('If review_status is incomplete, the reason why the tool loop was exhausted'),
+    parallelization_hint: z.enum(['serial', 'parallel', 'hybrid']).nullable().describe('Hint from reviewer: can this plan be parallelized?'),
+    coordination_risks: z.array(z.string()).nullable().describe('Coordination risks if parallelized'),
+    recommended_subtask_boundaries: z.array(z.string()).nullable().describe('Suggested subtask split boundaries'),
+    user_original_request_echo: z.string().nullable().describe('Verbatim echo of user_original_request so the reviewer commits to what it was asked to solve. Null only if the caller omitted user_original_request.'),
+    symptom_impact: z
+        .object({
+        before: z.string().describe('Observable symptom the user reported, in their own terms.'),
+        after: z.string().describe('What the user will observe after this plan is implemented.'),
+        causal_chain: z.string().describe("Why the planned change causes 'before' → 'after'."),
+    })
+        .nullable()
+        .describe('How the plan is expected to change the user-visible symptom. Null only if user_original_request was not supplied.'),
+    symptom_match_notes: z.string().nullable().describe('If plan does NOT clearly address the reported symptom, explain the gap here. Null if fully addressed.'),
+    gates_tripped: z.array(z.string()).nullable().describe('Server-populated list of post-LLM gate names that fired. Reviewer should leave null.'),
+});
+// Extended output with server-added fields (not sent to the reviewer model, used for MCP response)
+export const PlanReviewMcpOutputSchema = PlanReviewOutputSchema
+    .extend({
+    review_id: z.string().describe('Response ID for maintaining reviewer context across rounds. Pass as previous_review_id on the next call.'),
+})
+    .merge(IterationMetaOutputSchema)
+    .merge(TokenUsageOutputSchema);

package/build/services/filesystem-tools.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared filesystem tool executor used by all provider implementations.
+ * Handles all 8 standard tools + get_git_diff.
+ */
+import { type WorkspaceScope } from './filesystem.js';
+export declare function executeFilesystemTool(projectRoot: string, toolName: string, args: Record<string, unknown>, scope?: WorkspaceScope | null): Promise<string>;

package/build/services/filesystem-tools.js

@@ -0,0 +1,39 @@
+/**
+ * Shared filesystem tool executor used by all provider implementations.
+ * Handles all 8 standard tools + get_git_diff.
+ */
+import { readProjectFile, listProjectDirectory, searchInFiles, readProjectFileRange, statProjectFile, readJsonValue, listTrackedFiles, getGitDiff, } from './filesystem.js';
+export async function executeFilesystemTool(projectRoot, toolName, args, scope) {
+    try {
+        switch (toolName) {
+            case 'read_file': {
+                const result = await readProjectFile(projectRoot, args.path, scope);
+                if (result.length > 50_000) {
+                    return `\u26a0\ufe0f This file is large (${result.length} chars). Consider using read_file_range or search_in_files instead.\n\n${result}`;
+                }
+                return result;
+            }
+            case 'list_directory':
+                return await listProjectDirectory(projectRoot, args.path, scope);
+            case 'search_in_files':
+                return await searchInFiles(projectRoot, args.query, args.paths, args.glob, scope?.trackedOnly, scope?.workingDirectories, scope);
+            case 'read_file_range':
+                return await readProjectFileRange(projectRoot, args.path, args.start_line, args.end_line, scope);
+            case 'stat_file':
+                return await statProjectFile(projectRoot, args.path, scope);
+            case 'read_json':
+                return await readJsonValue(projectRoot, args.path, args.json_pointer, scope);
+            case 'list_tracked_files': {
+                const files = await listTrackedFiles(projectRoot, args.prefix, scope);
+                return files.join('\n') || 'No tracked files found.';
+            }
+            case 'get_git_diff':
+                return await getGitDiff(projectRoot, args.base, args.paths, scope);
+            default:
+                return `Unknown tool: ${toolName}`;
+        }
+    }
+    catch (error) {
+        return `Error: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}

package/build/services/filesystem.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Validates that project_root is a reasonable absolute path,
+ * not the filesystem root or a system directory.
+ */
+export declare function validateProjectRoot(projectRoot: string): void;
+/**
+ * List git-tracked files under a given prefix.
+ * Respects working_directories and supports linked roots via "linked:<index>:<prefix>" syntax.
+ */
+export declare function listTrackedFiles(root: string, prefix?: string, scope?: WorkspaceScope | null): Promise<string[]>;
+/**
+ * Check if a file is git-tracked.
+ */
+export declare function isTrackedFile(root: string, filePath: string): Promise<boolean>;
+/**
+ * Workspace scope resolution result.
+ */
+export interface WorkspaceScope {
+    root: string;
+    workingDirectories: string[] | null;
+    linkedRoots: string[];
+    trackedOnly: boolean;
+}
+/**
+ * Resolves workspace scope from input fields following precedence rules:
+ * 1. workspace_root (preferred)
+ * 2. project_root (deprecated fallback)
+ * 3. working_directories (allowlist intersection)
+ * 4. linked_roots (separate read-only scopes)
+ */
+export declare function resolveWorkspaceScope(input: {
+    workspace_root?: string;
+    project_root?: string;
+    working_directories?: string[];
+    linked_roots?: string[];
+    tracked_only?: boolean;
+}): WorkspaceScope | null;
+export declare function readProjectFile(projectRoot: string, filePath: string, scope?: WorkspaceScope | null): Promise<string>;
+export declare function listProjectDirectory(projectRoot: string, dirPath: string, scope?: WorkspaceScope | null): Promise<string>;
+/**
+ * Search for a pattern in files using rg (preferred), git grep, or grep fallback.
+ * Supports searching across primary root and linked roots.
+ */
+export declare function searchInFiles(root: string, query: string, paths?: string[], glob?: string, trackedOnly?: boolean, workingDirectories?: string[] | null, scope?: WorkspaceScope | null): Promise<string>;
+/**
+ * Read a specific line range from a file.
+ */
+export declare function readProjectFileRange(root: string, filePath: string, startLine: number, endLine: number, scope?: WorkspaceScope | null): Promise<string>;
+/**
+ * Get file metadata (size, type, modified time).
+ */
+export declare function statProjectFile(root: string, filePath: string, scope?: WorkspaceScope | null): Promise<string>;
+/**
+ * Read a JSON file, optionally extracting a value at a JSON pointer path.
+ * Pointer format: "/key/subkey/0" (RFC 6901 simplified).
+ */
+export declare function readJsonValue(root: string, filePath: string, pointer?: string, scope?: WorkspaceScope | null): Promise<string>;
+/**
+ * Run git diff within the workspace scope.
+ * Returns the diff output, capped at MAX_GIT_DIFF_BYTES.
+ *
+ * Defaults to `HEAD` (staged + unstaged vs last commit) rather than `HEAD~1`,
+ * so the reviewer sees only the current workspace changes.
+ *
+ * For untracked (new) files listed in `paths`, appends a synthetic diff
+ * generated via `git diff --no-index /dev/null <file>`, so newly added files
+ * are visible to the reviewer.
+ */
+export declare function getGitDiff(root: string, base?: string | null, paths?: string[] | null, scope?: WorkspaceScope | null): Promise<string>;