ast-mcp-server 0.3.0 → 0.5.0

package/dist/services/operations.js

@@ -1,17 +1,20 @@
 import { createHash, randomUUID } from "node:crypto";
 import { lstatSync, realpathSync } from "node:fs";
-import { open, readFile, rename, stat, unlink } from "node:fs/promises";
+import { link, open, readFile, rename, stat, unlink } from "node:fs/promises";
 import path from "node:path";
 import { createTwoFilesPatch } from "diff";
 import { LanguageVariant, Node, ScriptTarget, SyntaxKind, ts } from "ts-morph";
 import { compareDiagnostics, normalizeDiagnostic, } from "./diagnostics.js";
 import { createFreshProject, findDeclarationByName, getSourceFileOrThrow, invalidateProject, } from "./project.js";
 import { executableDeclaration } from "./symbols.js";
+import { buildClassScaffold } from "./scaffold.js";
 import { withWorkspaceFileLock } from "./runtime-state.js";
 import { createWorkspaceSnapshot, hashBytes, hashWorkspaceFiles } from "./workspace.js";
 const DEFAULT_OPERATION_TTL_MS = 15 * 60 * 1000;
 const DEFAULT_MAX_OPERATIONS = 100;
 const MAX_INLINE_PREVIEW_CHARS = 100_000;
+const ABSENT_FILE_HASH = "0".repeat(64);
+const DEFAULT_NEW_FILE_MODE = 0o644;
 const operations = new Map();
 const writeQueues = new Map();
 let operationTestHooks = {};
@@ -104,6 +107,53 @@ function assertSafeOperationFile(projectRoot, absolutePath, displayPath) {
         throw new Error(`Operation target escapes the project root: ${displayPath}`);
     }
 }
+function isCreatedFile(file) {
+    return file.originalHash === ABSENT_FILE_HASH;
+}
+function assertSafeNewOperationFile(projectRoot, absolutePath, displayPath) {
+    const relative = path.relative(projectRoot, absolutePath);
+    if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`)) {
+        throw new Error(`Operation target escapes the project root: ${displayPath}`);
+    }
+    try {
+        lstatSync(absolutePath);
+        throw new Error(`Operation target already exists: ${displayPath}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const parentPath = path.dirname(absolutePath);
+    const parentStat = lstatSync(parentPath);
+    if (parentStat.isSymbolicLink()) {
+        throw new Error(`Operation target parent must not be a symbolic link: ${displayPath}`);
+    }
+    if (!parentStat.isDirectory()) {
+        throw new Error(`Operation target parent must be a real directory: ${displayPath}`);
+    }
+    const canonicalParent = realpathSync(parentPath);
+    const sameParent = process.platform === "win32"
+        ? canonicalParent.toLowerCase() === parentPath.toLowerCase()
+        : canonicalParent === parentPath;
+    if (!sameParent) {
+        throw new Error(`Operation target parent traverses a symbolic link: ${displayPath}`);
+    }
+    const uid = process.getuid?.();
+    if (uid !== undefined && parentStat.uid !== uid) {
+        throw new Error(`Operation target parent is not owned by the current user: ${displayPath}`);
+    }
+}
+function assertSafeCreationState(projectRoot, absolutePath, displayPath) {
+    try {
+        lstatSync(absolutePath);
+        assertSafeOperationFile(projectRoot, absolutePath, displayPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        assertSafeNewOperationFile(projectRoot, absolutePath, displayPath);
+    }
+}
 async function createPlan(projectRootInput, kind, allowNewErrors, mutate) {
     pruneOperations();
     const context = createFreshProject(projectRootInput);
@@ -126,9 +176,28 @@ async function createPlan(projectRootInput, kind, allowNewErrors, mutate) {
     for (const sourceFile of context.project.getSourceFiles()) {
         const absolutePath = sourceFile.getFilePath();
         const originalText = originals.get(absolutePath);
-        if (originalText === undefined)
-            continue;
         const updatedText = sourceFile.getFullText();
+        if (originalText === undefined) {
+            const file = path.relative(context.projectRoot, absolutePath);
+            assertSafeNewOperationFile(context.projectRoot, absolutePath, file);
+            const originalBytes = Buffer.alloc(0);
+            const updatedBytes = Buffer.from(updatedText, "utf8");
+            files.push({
+                absolutePath,
+                file,
+                originalHash: ABSENT_FILE_HASH,
+                updatedHash: hashBytes(updatedBytes),
+                originalText: "",
+                updatedText,
+                originalBytes,
+                updatedBytes,
+                diff: createTwoFilesPatch("/dev/null", file, "", updatedText, "before", "after", {
+                    context: 3,
+                }),
+                mode: DEFAULT_NEW_FILE_MODE,
+            });
+            continue;
+        }
         if (updatedText === originalText)
             continue;
         const originalBytes = await readFile(absolutePath);
@@ -159,13 +228,13 @@ async function createPlan(projectRootInput, kind, allowNewErrors, mutate) {
     }
     const postWorkspaceFiles = new Map(workspaceBefore.files);
     for (const file of files) {
-        if (!postWorkspaceFiles.has(file.absolutePath)) {
+        if (!isCreatedFile(file) && !postWorkspaceFiles.has(file.absolutePath)) {
             throw new Error(`Affected file is missing from the workspace snapshot: ${file.file}`);
         }
         postWorkspaceFiles.set(file.absolutePath, file.updatedHash);
     }
     const postWorkspaceHash = hashWorkspaceFiles(postWorkspaceFiles);
-    const workspaceAfter = createWorkspaceSnapshot(context);
+    const workspaceAfter = createWorkspaceSnapshot(createFreshProject(context.tsConfigFilePath));
     if (workspaceAfter.digest !== workspaceBefore.digest) {
         throw new Error("Workspace changed while the operation was being prepared. Retry preparation.");
     }
@@ -261,6 +330,41 @@ export async function prepareReplaceBody(args) {
         return 0;
     });
 }
+export async function prepareScaffoldClass(args) {
+    if (path.isAbsolute(args.filePath)) {
+        throw new Error("Scaffold file_path must be project-relative.");
+    }
+    const normalizedFile = path.normalize(args.filePath);
+    if (normalizedFile === "." ||
+        normalizedFile === ".." ||
+        normalizedFile.startsWith(`..${path.sep}`) ||
+        normalizedFile !== args.filePath.split(path.posix.sep).join(path.sep)) {
+        throw new Error("Scaffold file_path must be normalized and remain inside the project root.");
+    }
+    if (!/\.(?:ts|tsx)$/.test(normalizedFile) || normalizedFile.endsWith(".d.ts")) {
+        throw new Error("Scaffold file_path must target a .ts or .tsx implementation file.");
+    }
+    let metadata;
+    const operation = await createPlan(args.projectRoot, "scaffold_class", args.allowNewErrors ?? false, (project, projectRoot) => {
+        const absolutePath = path.resolve(projectRoot, normalizedFile);
+        assertSafeNewOperationFile(projectRoot, absolutePath, normalizedFile);
+        const scaffold = buildClassScaffold(project, absolutePath, args.spec);
+        metadata = {
+            outline: scaffold.outline,
+            pendingMethods: scaffold.pendingMethods,
+        };
+        return 0;
+    });
+    if (!metadata)
+        throw new Error("Scaffold generation did not produce metadata.");
+    return {
+        operation,
+        file: normalizedFile.split(path.sep).join(path.posix.sep),
+        className: args.spec.className,
+        outline: metadata.outline,
+        pendingMethods: metadata.pendingMethods,
+    };
+}
 async function withWriteLock(key, callback) {
     const previous = writeQueues.get(key) ?? Promise.resolve();
     let release;
@@ -325,6 +429,24 @@ async function syncDirectories(files) {
         }
     }
 }
+async function currentWorkspaceHash(operation) {
+    const context = createFreshProject(operation.tsConfigFilePath);
+    const snapshot = createWorkspaceSnapshot(context);
+    const files = new Map(snapshot.files);
+    for (const file of operation.files) {
+        if (!isCreatedFile(file))
+            continue;
+        try {
+            files.set(file.absolutePath, hashBytes(await readFile(file.absolutePath)));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            files.delete(file.absolutePath);
+        }
+    }
+    return hashWorkspaceFiles(files);
+}
 function appliedResult(operation, idempotentReplay) {
     return {
         operation_id: operation.operation_id,
@@ -364,6 +486,7 @@ export async function applyOperation(operationId, planHash) {
     return withWriteLock(operation.tsConfigFilePath, async () => withWorkspaceFileLock(operation.tsConfigFilePath, { stateDirectory: operation.lockStateDirectory }, async () => {
         if (operation.status === "applied") {
             for (const file of operation.files) {
+                assertSafeOperationFile(operation.project_root, file.absolutePath, file.file);
                 const currentBytes = await readFile(file.absolutePath);
                 if (hashBytes(currentBytes) !== file.updatedHash) {
                     throw new Error(`Applied receipt conflict: ${file.file} no longer matches the recorded postimage.`);
@@ -380,12 +503,17 @@ export async function applyOperation(operationId, planHash) {
             throw new Error(operation.block_reason ?? "The operation is blocked by validation errors.");
         }
         for (const file of operation.files) {
-            assertSafeOperationFile(operation.project_root, file.absolutePath, file.file);
+            if (isCreatedFile(file)) {
+                assertSafeCreationState(operation.project_root, file.absolutePath, file.file);
+            }
+            else {
+                assertSafeOperationFile(operation.project_root, file.absolutePath, file.file);
+            }
         }
-        const currentContext = createFreshProject(operation.tsConfigFilePath);
-        const currentWorkspace = createWorkspaceSnapshot(currentContext);
-        if (currentWorkspace.digest === operation.post_workspace_hash) {
+        const workspaceHash = await currentWorkspaceHash(operation);
+        if (workspaceHash === operation.post_workspace_hash) {
             for (const file of operation.files) {
+                assertSafeOperationFile(operation.project_root, file.absolutePath, file.file);
                 const currentBytes = await readFile(file.absolutePath);
                 if (hashBytes(currentBytes) !== file.updatedHash) {
                     throw new Error(`Postimage recovery conflict: ${file.file} does not match the reviewed postimage.`);
@@ -397,10 +525,12 @@ export async function applyOperation(operationId, planHash) {
             await persistReceipt();
             return appliedResult(operation, true);
         }
-        if (currentWorkspace.digest !== operation.workspace_hash) {
+        if (workspaceHash !== operation.workspace_hash) {
             throw new Error("Conflict: the project source/config workspace changed after preparation. No files were written.");
         }
         for (const file of operation.files) {
+            if (isCreatedFile(file))
+                continue;
             const currentBytes = await readFile(file.absolutePath);
             if (hashBytes(currentBytes) !== file.originalHash) {
                 throw new Error(`Conflict: ${file.file} changed after the operation was prepared. No files were written.`);
@@ -413,6 +543,10 @@ export async function applyOperation(operationId, planHash) {
                 staged.set(file, await stageFile(file, operationId));
             }
             for (const file of operation.files) {
+                if (isCreatedFile(file)) {
+                    assertSafeNewOperationFile(operation.project_root, file.absolutePath, file.file);
+                    continue;
+                }
                 const currentBytes = await readFile(file.absolutePath);
                 if (hashBytes(currentBytes) !== file.originalHash) {
                     throw new Error(`Conflict: ${file.file} changed while the operation was being staged. No files were written.`);
@@ -420,9 +554,18 @@ export async function applyOperation(operationId, planHash) {
             }
             for (const [index, file] of operation.files.entries()) {
                 await operationTestHooks.beforeReplace?.(file.file, index);
-                await rename(staged.get(file), file.absolutePath);
-                staged.delete(file);
-                applied.push(file);
+                if (isCreatedFile(file)) {
+                    await link(staged.get(file), file.absolutePath);
+                    applied.push(file);
+                    await safeUnlink(staged.get(file));
+                    staged.delete(file);
+                }
+                else {
+                    await rename(staged.get(file), file.absolutePath);
+                    staged.delete(file);
+                    applied.push(file);
+                }
+                await operationTestHooks.afterReplace?.(file.file, index);
                 const writtenBytes = await readFile(file.absolutePath);
                 if (hashBytes(writtenBytes) !== file.updatedHash) {
                     throw new Error(`Post-write verification failed for ${file.file}.`);
@@ -439,7 +582,13 @@ export async function applyOperation(operationId, planHash) {
                         rollbackErrors.push(`${file.file}: current bytes no longer match this operation's postimage`);
                         continue;
                     }
-                    await restoreFile(file, operationId);
+                    if (isCreatedFile(file)) {
+                        assertSafeOperationFile(operation.project_root, file.absolutePath, file.file);
+                        await safeUnlink(file.absolutePath);
+                    }
+                    else {
+                        await restoreFile(file, operationId);
+                    }
                 }
                 catch (rollbackError) {
                     rollbackErrors.push(`${file.file}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
@@ -497,7 +646,6 @@ function containedOperationPath(projectRoot, file) {
     if (relative !== file.split(path.posix.sep).join(path.sep)) {
         throw new Error(`Persisted operation file path is not normalized: ${file}`);
     }
-    assertSafeOperationFile(projectRoot, absolutePath, file);
     return absolutePath;
 }
 export function exportOperationRecord(operationId) {
@@ -539,12 +687,19 @@ export function importOperationRecord(persisted, expectedPlanHash) {
         const absolutePath = containedOperationPath(context.projectRoot, file.file);
         const originalBytes = decodePersistedBytes(file.original_bytes_base64, `${file.file} original bytes`);
         const updatedBytes = decodePersistedBytes(file.updated_bytes_base64, `${file.file} updated bytes`);
-        if (hashBytes(originalBytes) !== file.original_hash) {
+        const createsFile = file.original_hash === ABSENT_FILE_HASH;
+        if (createsFile ? originalBytes.length !== 0 : hashBytes(originalBytes) !== file.original_hash) {
             throw new Error(`Persisted original hash mismatch for ${file.file}.`);
         }
         if (hashBytes(updatedBytes) !== file.updated_hash) {
             throw new Error(`Persisted updated hash mismatch for ${file.file}.`);
         }
+        if (createsFile) {
+            assertSafeCreationState(context.projectRoot, absolutePath, file.file);
+        }
+        else {
+            assertSafeOperationFile(context.projectRoot, absolutePath, file.file);
+        }
         const originalText = decodeSource(originalBytes, absolutePath);
         const updatedText = decodeSource(updatedBytes, absolutePath);
         return {
@@ -556,7 +711,7 @@ export function importOperationRecord(persisted, expectedPlanHash) {
             updatedText,
             originalBytes,
             updatedBytes,
-            diff: createTwoFilesPatch(file.file, file.file, originalText, updatedText, "before", "after", { context: 3 }),
+            diff: createTwoFilesPatch(createsFile ? "/dev/null" : file.file, file.file, originalText, updatedText, "before", "after", { context: 3 }),
             mode: file.mode,
         };
     });

package/dist/services/pagination.js

@@ -1,16 +1,22 @@
 import { z } from "zod";
 export const DEFAULT_PAGE_LIMIT = 100;
 export const MAX_PAGE_LIMIT = 500;
-export const PaginationInputSchema = {
-    offset: z.number().int().min(0).default(0).describe("Zero-based result offset."),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(MAX_PAGE_LIMIT)
-        .default(DEFAULT_PAGE_LIMIT)
-        .describe(`Maximum results to return (1-${MAX_PAGE_LIMIT}).`),
-};
+export function createPaginationInputSchema(defaultLimit = DEFAULT_PAGE_LIMIT) {
+    if (!Number.isInteger(defaultLimit) || defaultLimit < 1 || defaultLimit > MAX_PAGE_LIMIT) {
+        throw new Error(`Default page limit must be an integer from 1 to ${MAX_PAGE_LIMIT}.`);
+    }
+    return {
+        offset: z.number().int().min(0).default(0).describe("Zero-based result offset."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_PAGE_LIMIT)
+            .default(defaultLimit)
+            .describe(`Maximum results to return (1-${MAX_PAGE_LIMIT}).`),
+    };
+}
+export const PaginationInputSchema = createPaginationInputSchema();
 export const PaginationOutputSchema = {
     offset: z.number().int().min(0),
     limit: z.number().int().min(1),

package/dist/services/scaffold.js

@@ -0,0 +1,241 @@
+import { LanguageVariant, Node, Scope, ScriptTarget, SyntaxKind, ts, } from "ts-morph";
+import { buildFileOutline } from "./outline.js";
+function assertIdentifier(value, label) {
+    const scanner = ts.createScanner(ScriptTarget.Latest, false, LanguageVariant.Standard, value);
+    const valid = scanner.scan() === SyntaxKind.Identifier && scanner.scan() === SyntaxKind.EndOfFileToken;
+    if (!valid)
+        throw new Error(`${label} must be a valid TypeScript identifier.`);
+}
+function assertBoundedText(value, label, maximum = 10_000) {
+    if (value.trim().length === 0)
+        throw new Error(`${label} must not be empty.`);
+    if (value.length > maximum)
+        throw new Error(`${label} exceeds ${maximum} characters.`);
+}
+function parseFragment(sourceText, label) {
+    const sourceFile = ts.createSourceFile("__ast_scaffold_fragment.ts", sourceText, ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const diagnostics = sourceFile.parseDiagnostics;
+    if (diagnostics.length > 0) {
+        throw new Error(`${label} is not valid TypeScript in its declaration position.`);
+    }
+    return sourceFile;
+}
+function assertTypeFragment(value, label) {
+    assertBoundedText(value, label);
+    const sourceFile = parseFragment(`type __ScaffoldType = ${value};`, label);
+    const declaration = sourceFile.statements[0];
+    if (sourceFile.statements.length !== 1 ||
+        !declaration ||
+        !ts.isTypeAliasDeclaration(declaration) ||
+        declaration.type.getText(sourceFile) !== value.trim()) {
+        throw new Error(`${label} must contain exactly one TypeScript type.`);
+    }
+}
+function assertHeritageFragment(value, label, token) {
+    assertBoundedText(value, label);
+    const keyword = token === SyntaxKind.ExtendsKeyword ? "extends" : "implements";
+    const sourceFile = parseFragment(`class __Scaffold ${keyword} ${value} {}`, label);
+    const declaration = sourceFile.statements[0];
+    const clause = declaration && ts.isClassDeclaration(declaration)
+        ? declaration.heritageClauses?.find((item) => item.token === token)
+        : undefined;
+    if (sourceFile.statements.length !== 1 ||
+        !clause ||
+        clause.types.length !== 1 ||
+        clause.types[0]?.getText(sourceFile) !== value.trim()) {
+        throw new Error(`${label} must contain exactly one TypeScript heritage expression.`);
+    }
+}
+function assertInitializerFragment(value, label) {
+    assertBoundedText(value, label);
+    const sourceFile = parseFragment(`class __Scaffold { value = ${value}; }`, label);
+    const declaration = sourceFile.statements[0];
+    const members = declaration && ts.isClassDeclaration(declaration) ? declaration.members : [];
+    const property = members[0];
+    if (sourceFile.statements.length !== 1 ||
+        members.length !== 1 ||
+        !property ||
+        !ts.isPropertyDeclaration(property) ||
+        property.initializer?.getText(sourceFile) !== value.trim()) {
+        throw new Error(`${label} must contain exactly one TypeScript expression.`);
+    }
+}
+function scopeStructure(modifier) {
+    switch (modifier) {
+        case "public":
+            return { scope: Scope.Public };
+        case "public readonly":
+            return { scope: Scope.Public, isReadonly: true };
+        case "protected":
+            return { scope: Scope.Protected };
+        case "protected readonly":
+            return { scope: Scope.Protected, isReadonly: true };
+        case "private":
+            return { scope: Scope.Private };
+        case "private readonly":
+            return { scope: Scope.Private, isReadonly: true };
+        default:
+            return {};
+    }
+}
+function decoratorStructure(value, label) {
+    assertBoundedText(value, label);
+    const sourceFile = parseFragment(`${value.trim()}\nclass __Scaffold {}`, label);
+    const declaration = sourceFile.statements[0];
+    const decorators = declaration && ts.isClassDeclaration(declaration) && ts.canHaveDecorators(declaration)
+        ? ts.getDecorators(declaration)
+        : undefined;
+    if (sourceFile.statements.length !== 1 ||
+        decorators?.length !== 1 ||
+        decorators[0]?.getText(sourceFile) !== value.trim()) {
+        throw new Error(`${label} must contain exactly one TypeScript decorator.`);
+    }
+    const match = /^@([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)(?:\(([\s\S]*)\))?$/.exec(value.trim());
+    if (!match) {
+        throw new Error(`${label} must use @Name or @Name(arguments) syntax.`);
+    }
+    const argumentText = match[2]?.trim();
+    return {
+        name: match[1],
+        arguments: argumentText ? [argumentText] : [],
+    };
+}
+function validateSpec(spec) {
+    assertIdentifier(spec.className, "class_name");
+    if (spec.methods.length === 0)
+        throw new Error("methods must contain at least one method.");
+    const methodNames = new Set();
+    for (const [index, method] of spec.methods.entries()) {
+        assertIdentifier(method.name, `methods[${index}].name`);
+        if (method.name === "constructor") {
+            throw new Error('Method name "constructor" is reserved for the generated constructor.');
+        }
+        if (methodNames.has(method.name)) {
+            throw new Error("Method names must be unique so pending method selectors are unambiguous.");
+        }
+        methodNames.add(method.name);
+        assertTypeFragment(method.returnType, `methods[${index}].return_type`);
+        const parameterNames = new Set();
+        for (const [paramIndex, parameter] of method.params.entries()) {
+            assertIdentifier(parameter.name, `methods[${index}].params[${paramIndex}].name`);
+            if (parameterNames.has(parameter.name)) {
+                throw new Error(`methods[${index}] parameter names must be unique.`);
+            }
+            parameterNames.add(parameter.name);
+            assertTypeFragment(parameter.type, `methods[${index}].params[${paramIndex}].type`);
+        }
+        for (const [docsIndex, docs] of (method.docs ?? []).entries()) {
+            assertBoundedText(docs, `methods[${index}].docs[${docsIndex}]`);
+            if (docs.includes("*/")) {
+                throw new Error(`methods[${index}].docs[${docsIndex}] must not close its doc comment.`);
+            }
+        }
+    }
+    const constructorParameterNames = new Set();
+    for (const [index, parameter] of spec.constructorParams.entries()) {
+        assertIdentifier(parameter.name, `constructor_params[${index}].name`);
+        if (constructorParameterNames.has(parameter.name)) {
+            throw new Error("Constructor parameter names must be unique.");
+        }
+        constructorParameterNames.add(parameter.name);
+        assertTypeFragment(parameter.type, `constructor_params[${index}].type`);
+    }
+    const propertyNames = new Set();
+    for (const [index, property] of spec.properties.entries()) {
+        assertIdentifier(property.name, `properties[${index}].name`);
+        if (propertyNames.has(property.name))
+            throw new Error("Property names must be unique.");
+        if (methodNames.has(property.name)) {
+            throw new Error("Property names must not collide with generated method names.");
+        }
+        propertyNames.add(property.name);
+        assertTypeFragment(property.type, `properties[${index}].type`);
+        if (property.initializer === undefined) {
+            throw new Error(`properties[${index}] requires an initializer.`);
+        }
+        assertInitializerFragment(property.initializer, `properties[${index}].initializer`);
+    }
+    for (const [index, declaration] of spec.imports.entries()) {
+        assertBoundedText(declaration.from, `imports[${index}].from`, 500);
+        if ([...declaration.from].some((character) => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return codePoint <= 31 || codePoint === 127;
+        })) {
+            throw new Error(`imports[${index}].from must not contain control characters.`);
+        }
+        if (declaration.default !== undefined) {
+            assertIdentifier(declaration.default, `imports[${index}].default`);
+        }
+        for (const [nameIndex, name] of (declaration.named ?? []).entries()) {
+            assertIdentifier(name, `imports[${index}].named[${nameIndex}]`);
+        }
+    }
+    spec.decorators.forEach((decorator, index) => decoratorStructure(decorator, `decorators[${index}]`));
+    spec.methods.forEach((method, methodIndex) => (method.decorators ?? []).forEach((decorator, decoratorIndex) => decoratorStructure(decorator, `methods[${methodIndex}].decorators[${decoratorIndex}]`)));
+    if (spec.extends !== undefined) {
+        assertHeritageFragment(spec.extends, "extends", SyntaxKind.ExtendsKeyword);
+    }
+    spec.implements.forEach((value, index) => assertHeritageFragment(value, `implements[${index}]`, SyntaxKind.ImplementsKeyword));
+}
+export function buildClassScaffold(project, filePath, spec) {
+    validateSpec(spec);
+    const sourceFile = project.createSourceFile(filePath, "", { overwrite: false });
+    sourceFile.addImportDeclarations(spec.imports.map((declaration) => ({
+        moduleSpecifier: declaration.from,
+        ...(declaration.default ? { defaultImport: declaration.default } : {}),
+        ...(declaration.named?.length ? { namedImports: declaration.named } : {}),
+    })));
+    sourceFile.addClass({
+        name: spec.className,
+        isExported: true,
+        ...(spec.extends ? { extends: spec.extends } : {}),
+        ...(spec.implements.length > 0 ? { implements: spec.implements } : {}),
+        decorators: spec.decorators.map((decorator, index) => decoratorStructure(decorator, `decorators[${index}]`)),
+        ctors: spec.constructorParams.length > 0
+            ? [
+                {
+                    parameters: spec.constructorParams.map((parameter) => ({
+                        name: parameter.name,
+                        type: parameter.type,
+                        ...scopeStructure(parameter.accessModifier),
+                    })),
+                    statements: [],
+                },
+            ]
+            : [],
+        properties: spec.properties.map((property) => ({
+            name: property.name,
+            type: property.type,
+            ...scopeStructure(property.accessModifier),
+            ...(property.initializer !== undefined ? { initializer: property.initializer } : {}),
+        })),
+        methods: spec.methods.map((method, methodIndex) => ({
+            name: method.name,
+            isAsync: method.isAsync,
+            returnType: method.returnType,
+            ...scopeStructure(method.accessModifier),
+            parameters: method.params.map((parameter) => ({
+                name: parameter.name,
+                type: parameter.type,
+            })),
+            decorators: (method.decorators ?? []).map((decorator, decoratorIndex) => decoratorStructure(decorator, `methods[${methodIndex}].decorators[${decoratorIndex}]`)),
+            docs: method.docs ?? [],
+            statements: [`throw new Error("Not implemented: ${spec.className}.${method.name}");`],
+        })),
+    });
+    const classes = sourceFile.getClasses();
+    const allowedStatements = sourceFile
+        .getStatements()
+        .every((statement) => Node.isImportDeclaration(statement) || Node.isClassDeclaration(statement));
+    if (!allowedStatements ||
+        classes.length !== 1 ||
+        classes[0]?.getName() !== spec.className ||
+        classes[0].getMethods().length !== spec.methods.length) {
+        throw new Error("Generated scaffold failed structural postcondition validation.");
+    }
+    return {
+        sourceFile,
+        pendingMethods: spec.methods.map((method) => `${spec.className}.${method.name}`),
+        outline: buildFileOutline(sourceFile).text,
+    };
+}

package/dist/services/symbols.js

@@ -1,4 +1,20 @@
 import { Node, } from "ts-morph";
+export function symbolMatchRank(query, symbol) {
+    const normalizedQuery = query.toLowerCase();
+    const normalizedPath = symbol.symbolPath.toLowerCase();
+    const normalizedName = symbol.name.toLowerCase();
+    const normalizedSelector = `${normalizedPath}@${symbol.line}`;
+    if (normalizedSelector === normalizedQuery)
+        return 0;
+    if (normalizedPath === normalizedQuery)
+        return 1;
+    if (normalizedName === normalizedQuery)
+        return 2;
+    if (normalizedPath.startsWith(normalizedQuery) || normalizedName.startsWith(normalizedQuery)) {
+        return 3;
+    }
+    return 4;
+}
 function namedNode(node) {
     if (Node.isConstructorDeclaration(node))
         return "constructor";

package/dist/tools/apply_operation.js

@@ -7,7 +7,7 @@ const AstApplyOperationInputSchema = z.object({
 });
 const AstApplyOperationOutputSchema = z.object({
     operation_id: z.string().uuid(),
-    kind: z.enum(["rename_symbol", "replace_symbol_body"]),
+    kind: z.enum(["rename_symbol", "replace_symbol_body", "scaffold_class"]),
     status: z.literal("applied"),
     applied_at: z.string(),
     affected_files: z.array(z.string()),