expose manifest-driven project knowledge through MCP

This commit is contained in:
2026-09-29 08:30:38 +01:00
parent 9f61f9c07d
commit 58f11a8123
14 changed files with 665 additions and 13 deletions
@@ -186,6 +186,54 @@ points. A page returns referenceId, offset, total, text and nextOffset (null at
end). Invalid pagination fails; unknown/traversal-like IDs cannot escape the
index. Installed packaging and real provider resolution are steps 17–18.
### 5.1 Manifest and Provider Resolution
`studio_project_context` resolves an exact, canonical root registered by an open
project session. It does not use the focused window, accept a source-directory
path as a project root, acquire a manual lease, or require an AI grant. A session
is discoverable only after successful opening and until closure begins.
Unregistered/closed roots return `PROJECT_NOT_OPEN`.
Each call reads the saved `prometeu.json` and dependency manifests again. Missing
or invalid primary manifests fail explicitly instead of returning cached language
metadata. Languages are grouped by declared ID, with the primary flag derived
from the main manifest. Unknown IDs retain their identity and expose unsupported
build/LSP support; no default frontend is consulted.
Extensions and source roots come from the installed frontend specification.
LSP feature support comes from the same compiler bridge description used by the
existing LSP server, not from a duplicated PBS capability list. If that provider
cannot describe its LSP, support is UNKNOWN with an explicit limitation. These
are installed-provider capabilities, not a promise that the MCP language-query
tool is already composed or that any particular source file will compile.
Language versions remain unknown when no owner metadata exists. Compiler versions
use the installed frontend package's `Implementation-Version` only when present.
The requested SDK version has manifest provenance; the context distinguishes
versions supported by the installed provider from unsupported requests. Multiple
SDK requests for the same language yield an unknown aggregate version, an explicit
limitation and separate SDK library entries. These identifiers MUST NOT be
substituted for one another.
Dependency paths and registry entries use the compiler's existing resolver,
including its main-root-relative local path semantics and registry requirement.
Discovery does not create a registry, install dependencies or build sources.
Unresolved declarations remain visible with empty roots and limitations. Mixed
language graphs are described but reported as unsupported for the current build
pipeline. Discovery is bounded to 256 projects and 256 declarations per manifest.
The editable scope is the canonical project root **minus** read-only roots.
Read-only scope takes precedence: external/registry libraries and their transitive
dependencies remain protected even when stored beneath the project root or also
reachable through a local declaration. Source roots are canonicalized, including
symlink targets. SDK entries are always read-only; packaged SDK resources need not
have filesystem roots. Scope metadata does not sandbox an external agent's own
filesystem tools; the developer remains responsible for those tools and Git.
Paths in MCP results are absolute filesystem strings, not `file:` URIs. Until
step 18 packages the owner-maintained index, references/reference IDs are empty
with `DOCUMENTATION_UNAVAILABLE`; no guessed path or reference is advertised.
## 6. Image Contract
MCP image content has `type:image`, `mimeType:image/png`, and base64 `data` of
@@ -210,7 +258,8 @@ authentication, Origin, endpoint/method/version handling, tool dispatch, malform
or oversized input, closure, restart and old-token rejection. Provider doubles
exist only in tests. Composition starts/closes transport with Studio.
Step 16's production registry is empty until functional handlers are composed;
The production registry composes `studio_project_context` as of step 17; other
tools are advertised only when their functional handlers are connected.
DEV configuration-copy stays unavailable until step 21. Passing this transport
gate is not the phase 3 or final external-agent acceptance gate. API/Core and
JavaFX MUST NOT import MCP/HTTP implementations; architecture tests enforce it.
+1
View File
@@ -10,6 +10,7 @@ dependencies {
implementation(project(":prometeu-compiler:prometeu-compiler-core"))
implementation(project(":prometeu-compiler:prometeu-build-pipeline"))
implementation(project(":prometeu-compiler:prometeu-frontend-registry"))
implementation(project(":prometeu-compiler:prometeu-deps"))
implementation(project(":prometeu-packer:prometeu-packer-api"))
implementation(project(":prometeu-packer:prometeu-packer-v1"))
implementation(project(":prometeu-studio-api"))
@@ -296,9 +296,17 @@ public class StudioApplicationConfiguration {
}
@Bean
p.studio.app.mcp.McpToolRegistry mcpToolRegistry(p.studio.app.mcp.McpToolCatalog catalog, ObjectMapper mapper) {
// Providers are connected in PLN-0139 steps 17–20. Never advertise placeholders.
return new p.studio.app.mcp.McpToolRegistry(catalog, mapper, java.util.Map.of());
p.studio.api.automation.ProjectKnowledge projectKnowledge(
p.studio.core.project.ProjectAccessRegistry projects, ProjectCatalog catalog, ObjectMapper mapper) {
return new p.studio.app.compiler.CompilerProjectKnowledge(projects, catalog, mapper);
}
@Bean
p.studio.app.mcp.McpToolRegistry mcpToolRegistry(p.studio.app.mcp.McpToolCatalog catalog, ObjectMapper mapper,
p.studio.api.automation.ProjectKnowledge knowledge) {
// Further providers are connected in PLN-0139 steps 18–20. Never advertise placeholders.
return new p.studio.app.mcp.McpToolRegistry(catalog, mapper,
p.studio.app.mcp.McpProjectKnowledgeTools.handlers(knowledge, mapper));
}
@Bean(initMethod = "start", destroyMethod = "close")
@@ -0,0 +1,229 @@
package p.studio.app.compiler;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.automation.AutomationException;
import p.studio.api.automation.AutomationFailure;
import p.studio.api.automation.ProjectKnowledge;
import p.studio.api.project.ProjectCatalog;
import p.studio.api.project.ProjectReference;
import p.studio.compiler.FrontendRegistryService;
import p.studio.compiler.dtos.PrometeuManifestDTO;
import p.studio.compiler.messages.BuildingIssueSink;
import p.studio.compiler.workspaces.phases.DependencyResolver;
import p.studio.core.project.ProjectAccessRegistry;
import p.studio.lsp.messages.LspProjectContext;
import p.studio.lsp.services.compiler.CompilerLanguageServiceBridge;
import java.io.IOException;
import java.nio.file.Path;
import java.util.*;
/** Read-only manifest/provider discovery. Never selects a default frontend or starts a build. */
public final class CompilerProjectKnowledge implements ProjectKnowledge {
private static final int MAX_PROJECTS = 256;
private final ProjectAccessRegistry openProjects;
private final ProjectCatalog projects;
private final ObjectMapper mapper;
private final CompilerLanguageServiceBridge languageBridge = new CompilerLanguageServiceBridge();
public CompilerProjectKnowledge(ProjectAccessRegistry openProjects, ProjectCatalog projects, ObjectMapper mapper) {
this.openProjects = Objects.requireNonNull(openProjects);
this.projects = Objects.requireNonNull(projects);
this.mapper = Objects.requireNonNull(mapper);
}
@Override public Context context(Path openProjectRoot) {
Path root = openProjects.requireOpenRoot(openProjectRoot);
var limitations = new ArrayList<String>();
var discovered = new LinkedHashMap<Path, ProjectReference>();
var dependencies = new LinkedHashMap<Path, List<Path>>();
var readOnly = new LinkedHashSet<Path>();
var unresolved = new ArrayList<Library>();
var pending = new ArrayDeque<Path>();
var visited = new HashSet<Path>();
pending.add(root);
boolean dependenciesComplete = true;
while (!pending.isEmpty()) {
Path current = pending.removeFirst();
if (!visited.add(current)) continue;
if (visited.size() > MAX_PROJECTS)
throw new AutomationException(AutomationFailure.Code.LIMIT_EXCEEDED, "Project graph exceeds " + MAX_PROJECTS + " projects");
ProjectReference project;
PrometeuManifestDTO manifest;
try {
project = projects.openProject(current);
manifest = mapper.readValue(current.resolve("prometeu.json").toFile(), PrometeuManifestDTO.class);
} catch (IOException | RuntimeException failure) {
if (current.equals(root))
throw new AutomationException(AutomationFailure.Code.INFRASTRUCTURE_FAILURE, "Cannot read the current project manifest");
dependenciesComplete = false;
limitations.add("Dependency manifest unavailable: " + current);
unresolved.add(new Library(current.toString(), Version.unknown(), List.of(current), false));
readOnly.add(current);
dependencies.put(current, List.of());
continue;
}
discovered.put(current, project);
var children = new ArrayList<Path>();
dependencies.put(current, children);
if (manifest.dependencies() == null) continue;
if (manifest.dependencies().size() > MAX_PROJECTS)
throw new AutomationException(AutomationFailure.Code.LIMIT_EXCEEDED, "Too many dependency declarations");
for (var declaration : manifest.dependencies()) {
if (declaration == null
|| declaration instanceof PrometeuManifestDTO.DependencyDeclaration.Local local
&& (local.path() == null || local.path().isBlank())
|| declaration instanceof PrometeuManifestDTO.DependencyDeclaration.Registry registry
&& (registry.name() == null || registry.name().isBlank() || registry.version() == null || registry.version().isBlank()))
throw new AutomationException(AutomationFailure.Code.INFRASTRUCTURE_FAILURE, "Invalid dependency declaration in " + current);
var issues = BuildingIssueSink.empty();
// The compiler resolves even transitive local paths and registry entries against the main root.
var resolved = DependencyResolver.resolveDependencies(root, List.of(declaration), issues);
if (issues.hasErrors() || resolved.isEmpty()) {
dependenciesComplete = false;
String id = declaration instanceof PrometeuManifestDTO.DependencyDeclaration.Registry registry
? registry.name() + "@" + registry.version()
: String.valueOf(((PrometeuManifestDTO.DependencyDeclaration.Local) declaration).path());
var version = declaration instanceof PrometeuManifestDTO.DependencyDeclaration.Registry registry
&& registry.version() != null && !registry.version().isBlank()
? new Version(registry.version(), current.resolve("prometeu.json") + "#dependencies (requested)") : Version.unknown();
unresolved.add(new Library(id, version, List.of(), false));
limitations.add("Dependency could not be resolved by the compiler: " + id + " (declared by " + current + ")");
continue;
}
Path child = resolved.getFirst().canonPath();
children.add(child);
if (!child.startsWith(root) || declaration instanceof PrometeuManifestDTO.DependencyDeclaration.Registry)
readOnly.add(child);
pending.add(child);
}
}
// Read-only provenance wins if a library is reachable through more than one declaration.
boolean changed;
do {
changed = false;
for (var edge : dependencies.entrySet())
if (readOnly.stream().anyMatch(edge.getKey()::startsWith))
changed |= readOnly.addAll(edge.getValue());
} while (changed);
var protectedSources = new LinkedHashSet<Path>();
for (var project : discovered.values()) {
if (readOnly.stream().anyMatch(project.rootPath()::startsWith))
FrontendRegistryService.getProvider(project.languageId()).ifPresent(provider ->
provider.specification().getSourceRoots().forEach(relative ->
protectedSources.add(canonical(project.rootPath().resolve(relative)))));
}
readOnly.addAll(protectedSources);
var libraries = new ArrayList<Library>();
var byLanguage = new LinkedHashMap<String, List<ProjectReference>>();
for (var entry : discovered.entrySet()) {
var project = entry.getValue();
byLanguage.computeIfAbsent(project.languageId(), ignored -> new ArrayList<>()).add(project);
if (!entry.getKey().equals(root)) {
boolean editable = entry.getKey().startsWith(root) && readOnly.stream().noneMatch(entry.getKey()::startsWith);
libraries.add(new Library(project.name(), new Version(project.version(), entry.getKey().resolve("prometeu.json") + "#version"),
List.of(entry.getKey()), editable));
}
}
libraries.addAll(unresolved);
var languages = new ArrayList<Language>();
String primary = discovered.get(root).languageId();
if (byLanguage.size() > 1) limitations.add("The installed build pipeline requires the same language across the dependency graph");
for (var entry : byLanguage.entrySet()) {
var language = language(entry.getKey(), entry.getValue(), primary.equals(entry.getKey()),
dependenciesComplete && byLanguage.size() == 1, limitations);
languages.add(language);
for (Path source : language.sourceRoots()) if (!source.startsWith(root)) readOnly.add(source);
for (var project : entry.getValue()) {
var sdk = new Library("sdk:" + entry.getKey() + ":" + project.stdlibVersion(),
new Version(Integer.toString(project.stdlibVersion()), project.rootPath().resolve("prometeu.json") + "#stdlib (requested)"),
List.of(), false);
if (libraries.stream().noneMatch(item -> item.id().equals(sdk.id()))) libraries.add(sdk);
}
}
limitations.add("SDK resources are provider-owned, read-only resources, not editable project files");
limitations.add("DOCUMENTATION_UNAVAILABLE: installed language/SDK reference index is not yet available");
// Closing a project during discovery must not publish a successful context for that closed project.
openProjects.requireOpenRoot(root);
return new Context(root, discovered.get(root).name(), languages, libraries,
List.of(root), List.copyOf(readOnly), List.of(), limitations);
}
private Language language(String id, List<ProjectReference> projects, boolean primary,
boolean graphBuildable, List<String> limitations) {
var sdkVersions = projects.stream().map(ProjectReference::stdlibVersion).distinct().toList();
Version sdk = sdkVersions.size() == 1
? new Version(sdkVersions.getFirst().toString(), "prometeu.json#stdlib (requested)") : Version.unknown();
if (sdkVersions.size() != 1) limitations.add("Multiple SDK versions requested for " + id + ": " + sdkVersions);
var provider = FrontendRegistryService.getProvider(id);
if (provider.isEmpty()) {
limitations.add("UNSUPPORTED_LANGUAGE: no installed frontend for " + id);
return new Language(id, primary, Version.unknown(), Version.unknown(), sdk, List.of(), List.of(),
List.of(capability("build", false), capability("lsp", false)), List.of());
}
var spec = provider.get().specification();
var roots = new LinkedHashSet<Path>();
projects.forEach(project -> spec.getSourceRoots().forEach(relative -> roots.add(canonical(project.rootPath().resolve(relative)))));
boolean sdkSupported = sdkVersions.stream().allMatch(version -> spec.getStdlibVersions().stream().anyMatch(item -> item.version() == version));
if (!sdkSupported) limitations.add("Unsupported requested SDK version for " + id + ": " + sdkVersions);
if (sdkSupported && sdk.known()) sdk = new Version(sdk.value(), "prometeu.json#stdlib; supported by installed frontend");
var capabilities = new ArrayList<Capability>();
capabilities.add(capability("build", graphBuildable && sdkSupported));
var project = projects.getFirst();
addLspCapabilities(id, project, capabilities, limitations);
String compilerVersion = provider.get().getClass().getPackage().getImplementationVersion();
return new Language(id, primary, Version.unknown(), compilerVersion == null || compilerVersion.isBlank()
? Version.unknown() : new Version(compilerVersion, "installed frontend package Implementation-Version"), sdk,
spec.getAllowedExtensions().stream().sorted().toList(), List.copyOf(roots), capabilities, List.of());
}
private void addLspCapabilities(String id, ProjectReference project, List<Capability> capabilities, List<String> limitations) {
final p.studio.lsp.messages.BaselineServerDescription server;
try {
server = languageBridge.describeServer(new LspProjectContext(project.rootPath().toString(), id, project.rootPath()));
} catch (RuntimeException unavailable) {
String reason = "Installed frontend cannot describe LSP capabilities for " + id;
capabilities.add(new Capability("lsp", Support.UNKNOWN, reason));
limitations.add(reason);
return;
}
capabilities.add(capability("lsp", true));
capabilities.add(capability("diagnostics", true));
capabilities.add(capability("hover", server.hoverSupported()));
capabilities.add(capability("completion", server.completionSupported()));
capabilities.add(capability("signatureHelp", server.signatureHelpSupported()));
capabilities.add(capability("definition", server.definitionSupported()));
capabilities.add(capability("references", server.referencesSupported()));
capabilities.add(capability("documentSymbols", server.documentSymbolsSupported()));
capabilities.add(capability("workspaceSymbols", server.workspaceSymbolsSupported()));
capabilities.add(capability("rename", server.renameSupported()));
capabilities.add(capability("codeActions", server.codeActionsSupported()));
capabilities.add(capability("documentLinks", server.documentLinksSupported()));
capabilities.add(capability("foldingRanges", server.foldingRangesSupported()));
capabilities.add(capability("selectionRanges", server.selectionRangesSupported()));
capabilities.add(capability("formatting", server.formattingSupported()));
capabilities.add(capability("callHierarchy", server.callHierarchySupported()));
capabilities.add(capability("typeHierarchy", false));
}
private static Capability capability(String name, boolean supported) {
return new Capability(name, supported ? Support.SUPPORTED : Support.UNSUPPORTED,
supported ? null : "Not supported by the installed provider or current project dependency/SDK configuration");
}
private static Path canonical(Path path) {
Path normalized = path.toAbsolutePath().normalize();
try { return normalized.toRealPath(); }
catch (IOException ignored) {
Path parent = normalized.getParent();
return parent == null ? normalized : canonical(parent).resolve(normalized.getFileName());
}
}
@Override public ReferencePage readReference(Path openProjectRoot, String referenceId, int offset, int limit) {
openProjects.requireOpenRoot(openProjectRoot);
throw new AutomationException(AutomationFailure.Code.DOCUMENTATION_UNAVAILABLE, "No installed reference index is available");
}
}
@@ -0,0 +1,24 @@
package p.studio.app.mcp;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.module.SimpleModule;
import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
import p.studio.api.automation.ProjectKnowledge;
import java.nio.file.Path;
import java.util.Map;
import java.util.function.Function;
/** Context reads need authentication at transport level, but no control grant or task. */
public final class McpProjectKnowledgeTools {
private McpProjectKnowledgeTools() {}
public static Map<String, Function<JsonNode, McpToolResult>> handlers(ProjectKnowledge knowledge, ObjectMapper mapper) {
// Jackson's default Path serializer produces file: URIs; the public contract uses absolute paths.
var paths = new SimpleModule().addSerializer(Path.class, new ToStringSerializer());
var wireMapper = mapper.copy().registerModule(paths);
return Map.of("studio_project_context", arguments -> McpToolResult.success(mapper,
wireMapper.valueToTree(knowledge.context(Path.of(arguments.path("projectRoot").asText())))));
}
}
@@ -27,6 +27,9 @@ public final class McpToolRegistry {
if (handler == null) throw new IllegalArgumentException("Unknown or unavailable tool");
catalog.validateArguments(name, arguments);
try { return handler.apply(arguments); }
catch (p.studio.api.automation.AutomationException failure) {
return McpToolResult.failure(mapper, failure.failure());
}
catch (ControlDeniedException denied) {
var code = switch (denied.status()) {
case INVALID_TASK -> AutomationFailure.Code.INVALID_TASK;
@@ -29,7 +29,9 @@ class StudioApplicationConfigurationTest {
assertFalse(context.getClass().getName().contains("WebServer"));
assertFalse(executor.isShutdown());
assertTrue(mcp.isRunning());
assertTrue(context.getBean(p.studio.app.mcp.McpToolRegistry.class).descriptors().isEmpty());
var tools = context.getBean(p.studio.app.mcp.McpToolRegistry.class).descriptors();
org.junit.jupiter.api.Assertions.assertEquals(1, tools.size());
org.junit.jupiter.api.Assertions.assertEquals("studio_project_context", tools.get(0).path("name").asText());
}
assertTrue(executor.isShutdown());
assertFalse(mcp.isRunning());
@@ -0,0 +1,193 @@
package p.studio.app.compiler;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import p.studio.api.automation.*;
import p.studio.compiler.FrontendRegistryService;
import p.studio.compiler.models.FrontendSpec;
import p.studio.compiler.services.FrontendPhaseService;
import p.studio.compiler.services.FrontendProvider;
import p.studio.core.project.*;
import p.studio.utilities.structures.ReadOnlySet;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import static org.junit.jupiter.api.Assertions.*;
class CompilerProjectKnowledgeTest {
@TempDir Path directory;
final ObjectMapper mapper = new ObjectMapper();
final ProjectAccessRegistry access = new ProjectAccessRegistry();
CompilerProjectKnowledge knowledge() {
return new CompilerProjectKnowledge(access,
new ProjectCatalogService(directory, mapper, new ProjectLocalStudioSetupStore(mapper)), mapper);
}
@Test void pbsContextIsReadOnlyManifestDrivenAndVersionsAreIndependent() throws Exception {
Path root = project("game", "pbs", "1", "[]");
access.register(root, () -> { throw new AssertionError("No grant needed"); }, () -> true);
var result = knowledge().context(root);
var language = result.languages().getFirst();
assertEquals("pbs", language.id());
assertTrue(language.primary());
assertEquals(List.of("barrel", "pbs"), language.extensions());
assertEquals(List.of(root.resolve("src")), language.sourceRoots());
assertFalse(language.languageVersion().known());
assertFalse(language.compilerVersion().known());
assertEquals("1", language.sdkVersion().value());
assertTrue(language.sdkVersion().source().contains("supported by installed"));
assertSupport(language, "build", ProjectKnowledge.Support.SUPPORTED);
assertSupport(language, "definition", ProjectKnowledge.Support.SUPPORTED);
assertSupport(language, "typeHierarchy", ProjectKnowledge.Support.UNSUPPORTED);
assertEquals(List.of(root), result.editableRoots());
assertFalse(result.libraries().getFirst().editable());
assertTrue(result.libraries().getFirst().id().startsWith("sdk:pbs:"));
assertTrue(result.references().isEmpty());
assertTrue(result.limitations().stream().anyMatch(value -> value.contains("DOCUMENTATION_UNAVAILABLE")));
assertFalse(Files.exists(root.resolve(".workspace")));
assertFalse(Files.exists(root.resolve(".studio")));
}
@Test void rereadsSavedManifestAndNeverFallsBackForAnUnknownLanguageOrSdk() throws Exception {
Path root = project("game", "pbs", "1", "[]");
var registration = access.register(root, () -> () -> {}, () -> true);
var knowledge = knowledge();
assertEquals("pbs", knowledge.context(root).languages().getFirst().id());
project("game", "missing-language", "9", "[]");
var unknown = knowledge.context(root).languages().getFirst();
assertEquals("missing-language", unknown.id());
assertTrue(unknown.extensions().isEmpty());
assertTrue(unknown.sourceRoots().isEmpty());
assertSupport(unknown, "build", ProjectKnowledge.Support.UNSUPPORTED);
assertEquals("9", unknown.sdkVersion().value());
assertTrue(unknown.sdkVersion().source().contains("requested"));
project("game", "pbs", "999", "[]");
assertSupport(knowledge.context(root).languages().getFirst(), "build", ProjectKnowledge.Support.UNSUPPORTED);
registration.unsubscribe();
assertEquals(AutomationFailure.Code.PROJECT_NOT_OPEN,
assertThrows(AutomationException.class, () -> knowledge.context(root)).failure().code());
}
@Test void alternateInstalledMetadataUsesItsOwnExtensionsSdkAndLspCapabilitiesWithoutCompiling() throws Exception {
String id = "context-test-language";
FrontendRegistryService.register(new FrontendProvider() {
@Override public FrontendSpec specification() {
return FrontendSpec.builder().languageId(id).allowedExtensions(ReadOnlySet.from("alt"))
.sourceRoots(ReadOnlySet.from("code")).stdlibVersions(List.of(FrontendSpec.Stdlib.asDefault(7)))
// Reuse only a visual-theme fixture; no PBS compiler or language service is installed for this ID.
.semanticPresentation(FrontendRegistryService.require("pbs").specification().getSemanticPresentation()).build();
}
@Override public FrontendPhaseService compiler() { throw new AssertionError("Discovery must not compile"); }
});
try {
Path root = project("alternate", id, "7", "[]");
access.register(root, () -> () -> {}, () -> true);
var language = knowledge().context(root).languages().getFirst();
assertEquals(id, language.id());
assertEquals(List.of("alt"), language.extensions());
assertEquals(List.of(root.resolve("code")), language.sourceRoots());
assertEquals("7", language.sdkVersion().value());
assertSupport(language, "build", ProjectKnowledge.Support.SUPPORTED);
assertSupport(language, "definition", ProjectKnowledge.Support.UNSUPPORTED);
assertSupport(language, "formatting", ProjectKnowledge.Support.UNSUPPORTED);
assertFalse(language.languageVersion().known());
} finally { FrontendRegistryService.unregister(id); }
}
@Test void localExternalRegistryAndSymlinkLibrariesHaveCanonicalScopes() throws Exception {
Path root = project("game", "pbs", "1", """
[{"path":"lib"},{"path":"external-alias"},{"name":"registered","version":"1.0.0"}]
""");
Path local = project("game/lib", "pbs", "1", "[]");
Path external = project("external", "pbs", "1", "[]");
Path registered = project("game/vendor", "pbs", "1", "[]");
Files.createSymbolicLink(root.resolve("external-alias"), external);
Files.createDirectories(root.resolve(".workspace/repos"));
mapper.writeValue(root.resolve(".workspace/repos/registry.json").toFile(), java.util.Map.of("registered@1.0.0", registered.toString()));
access.register(root, () -> () -> {}, () -> true);
var result = knowledge().context(root);
assertTrue(library(result, local).editable());
assertFalse(library(result, external).editable());
assertFalse(library(result, registered).editable());
assertTrue(result.readOnlyRoots().contains(external));
assertTrue(result.readOnlyRoots().contains(registered));
}
@Test void externalSourceRootsAreReadOnlyAndUnresolvedDependenciesAreVisible() throws Exception {
Path root = project("game", "pbs", "1", "[{\"path\":\"missing\"}]");
Path externalSources = Files.createDirectory(directory.resolve("external-sources")).toRealPath();
Files.createSymbolicLink(root.resolve("src"), externalSources);
access.register(root, () -> () -> {}, () -> true);
var result = knowledge().context(root);
assertTrue(result.readOnlyRoots().contains(externalSources));
assertTrue(result.libraries().stream().anyMatch(library -> library.id().equals("missing") && library.roots().isEmpty() && !library.editable()));
assertSupport(result.languages().getFirst(), "build", ProjectKnowledge.Support.UNSUPPORTED);
assertTrue(result.limitations().stream().anyMatch(value -> value.contains("could not be resolved")));
assertFalse(Files.exists(root.resolve(".workspace")));
}
@Test void invalidOrMissingManifestIsATypedFailureNotAStaleContext() throws Exception {
Path root = project("game", "pbs", "1", "[]");
access.register(root, () -> () -> {}, () -> true);
Files.writeString(root.resolve("prometeu.json"), "{}");
assertEquals(AutomationFailure.Code.INFRASTRUCTURE_FAILURE,
assertThrows(AutomationException.class, () -> knowledge().context(root)).failure().code());
Files.delete(root.resolve("prometeu.json"));
assertEquals(AutomationFailure.Code.INFRASTRUCTURE_FAILURE,
assertThrows(AutomationException.class, () -> knowledge().context(root)).failure().code());
}
@Test void transitiveReadOnlyProvenanceWinsAndMixedLanguagesRemainVisible() throws Exception {
Path root = project("game", "pbs", "1", "[{\"path\":\"lib\"},{\"path\":\"../external\"}]");
Path local = project("game/lib", "pbs", "1", "[]");
Path external = project("external", "unknown-language", "2", "[{\"path\":\"lib\"}]");
Files.createDirectories(root.resolve(".workspace/repos"));
Files.writeString(root.resolve(".workspace/repos/registry.json"), "{}");
access.register(root, () -> () -> {}, () -> true);
var result = knowledge().context(root);
assertFalse(library(result, local).editable());
assertFalse(library(result, external).editable());
assertTrue(result.readOnlyRoots().contains(local.resolve("src")));
assertEquals(List.of("pbs", "unknown-language"), result.languages().stream().map(ProjectKnowledge.Language::id).toList());
assertFalse(result.languages().get(1).primary());
assertSupport(result.languages().getFirst(), "build", ProjectKnowledge.Support.UNSUPPORTED);
}
@Test void incompleteInstalledLspMetadataReportsUnknownInsteadOfInventingCapabilities() throws Exception {
String id = "incomplete-test-language";
FrontendRegistryService.register(new FrontendProvider() {
@Override public FrontendSpec specification() {
return FrontendSpec.builder().languageId(id).allowedExtensions(ReadOnlySet.from("alt"))
.sourceRoots(ReadOnlySet.from("code")).build();
}
@Override public FrontendPhaseService compiler() { throw new AssertionError("Discovery must not compile"); }
});
try {
Path root = project("alternate", id, "1", "[]");
access.register(root, () -> () -> {}, () -> true);
var result = knowledge().context(root);
assertSupport(result.languages().getFirst(), "lsp", ProjectKnowledge.Support.UNKNOWN);
assertTrue(result.limitations().stream().anyMatch(value -> value.contains("cannot describe LSP")));
} finally { FrontendRegistryService.unregister(id); }
}
private Path project(String name, String language, String sdk, String dependencies) throws Exception {
Path root = Files.createDirectories(directory.resolve(name)).toRealPath();
var manifest = mapper.createObjectNode().put("name", name).put("version", "1.0.0")
.put("language", language).put("stdlib", sdk).put("target", "Game");
manifest.set("dependencies", mapper.readTree(dependencies));
mapper.writeValue(root.resolve("prometeu.json").toFile(), manifest);
return root;
}
private ProjectKnowledge.Library library(ProjectKnowledge.Context context, Path root) {
return context.libraries().stream().filter(library -> library.roots().contains(root)).findFirst().orElseThrow();
}
private void assertSupport(ProjectKnowledge.Language language, String name, ProjectKnowledge.Support support) {
assertEquals(support, language.capabilities().stream().filter(capability -> capability.name().equals(name)).findFirst().orElseThrow().support());
}
}
@@ -103,6 +103,38 @@ class LocalMcpServerTest {
assertTrue(result.path("isError").asBoolean()); assertEquals("NOT_GRANTED", result.path("structuredContent").path("error").path("code").asText());
}
@Test void realContextHandlerReadsAnOpenProjectWithoutGrantAndRejectsItAfterClose(
@org.junit.jupiter.api.io.TempDir java.nio.file.Path temporary) throws Exception {
var root = temporary.toRealPath();
java.nio.file.Files.writeString(root.resolve("prometeu.json"), """
{"name":"HTTP context","version":"1.0.0","language":"pbs","stdlib":"1","target":"Game","dependencies":[]}
""");
var open = new p.studio.core.project.ProjectAccessRegistry();
var registration = open.register(root, () -> { throw new AssertionError("Context must not acquire manual control"); }, () -> true);
var catalog = new p.studio.core.project.ProjectCatalogService(root, mapper,
new p.studio.core.project.ProjectLocalStudioSetupStore(mapper));
var knowledge = new p.studio.app.compiler.CompilerProjectKnowledge(open, catalog, mapper);
server.close();
server = new LocalMcpServer(mapper, new McpToolRegistry(new McpToolCatalog(mapper), mapper,
McpProjectKnowledgeTools.handlers(knowledge, mapper)));
server.start();
initialize();
var call = mapper.createObjectNode().put("jsonrpc", "2.0").put("id", 2).put("method", "tools/call");
call.putObject("params").put("name", "studio_project_context").putObject("arguments").put("projectRoot", root.toString());
var wire = mapper.readTree(post(call.toString()).body()).path("result");
assertFalse(wire.path("isError").asBoolean());
var value = wire.path("structuredContent").path("value");
assertEquals(root.toString(), value.path("projectRoot").asText());
assertEquals(root.toString(), value.path("editableRoots").get(0).asText());
assertEquals("pbs", value.path("languages").get(0).path("id").asText());
assertTrue(value.path("languages").get(0).path("languageVersion").path("value").isNull());
assertFalse(java.nio.file.Files.exists(root.resolve(".studio")));
registration.unsubscribe();
var denied = mapper.readTree(post(call.toString()).body()).path("result");
assertTrue(denied.path("isError").asBoolean());
assertEquals("PROJECT_NOT_OPEN", denied.path("structuredContent").path("error").path("code").asText());
}
@Test void hostileHostAndDuplicateOriginAreRejectedEvenWithValidCredentials() throws Exception {
var connection = server.connection();
try (var socket = new java.net.Socket("127.0.0.1", connection.endpoint().getPort())) {
@@ -0,0 +1,15 @@
package p.studio.api.automation;
import java.util.Objects;
/** Expected service failure, independent of the transport used by an automation client. */
public final class AutomationException extends IllegalStateException {
private final AutomationFailure failure;
public AutomationException(AutomationFailure.Code code, String message) {
super(message);
failure = new AutomationFailure(Objects.requireNonNull(code), message);
}
public AutomationFailure failure() { return failure; }
}
@@ -8,15 +8,39 @@ import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.function.Supplier;
import java.util.function.BooleanSupplier;
import p.studio.api.automation.AutomationException;
import p.studio.api.automation.AutomationFailure;
/** Application-composed routing only; authority is owned by each project session. */
public final class ProjectAccessRegistry implements ProjectAccess {
private final Map<Path, Supplier<ManualLease>> projects = new HashMap<>();
private record Entry(Supplier<ManualLease> authority, BooleanSupplier available) {}
private final Map<Path, Entry> projects = new HashMap<>();
public synchronized OperationSubscription register(Path root, Supplier<ManualLease> authority) {
public OperationSubscription register(Path root, Supplier<ManualLease> authority) {
return register(root, authority, () -> false);
}
public synchronized OperationSubscription register(Path root, Supplier<ManualLease> authority, BooleanSupplier available) {
Path key = canonical(root);
if (projects.putIfAbsent(key, authority) != null) throw new IllegalStateException("Project already open: " + key);
return () -> { synchronized (this) { projects.remove(key, authority); } };
var entry = new Entry(java.util.Objects.requireNonNull(authority), java.util.Objects.requireNonNull(available));
if (projects.putIfAbsent(key, entry) != null) throw new IllegalStateException("Project already open: " + key);
return () -> { synchronized (this) { projects.remove(key, entry); } };
}
/** Exact root lookup, never focus-based or a descendant-path admission. No grant is needed. */
public Path requireOpenRoot(Path root) {
Path key = canonical(root);
Entry entry;
synchronized (this) { entry = projects.get(key); }
// Never call session code while holding the routing lock.
if (!root.isAbsolute() || entry == null || !entry.available().getAsBoolean())
throw new AutomationException(AutomationFailure.Code.PROJECT_NOT_OPEN, "The explicit project root is not open");
synchronized (this) {
if (projects.get(key) != entry)
throw new AutomationException(AutomationFailure.Code.PROJECT_NOT_OPEN, "The project was closed");
}
return key;
}
@Override public ManualLease enterManual(Path path) {
@@ -25,7 +49,7 @@ public final class ProjectAccessRegistry implements ProjectAccess {
Path key = canonical(path);
authority = projects.entrySet().stream().filter(e -> key.startsWith(e.getKey()))
.max(java.util.Comparator.comparingInt(e -> e.getKey().getNameCount()))
.map(Map.Entry::getValue).orElse(null);
.map(e -> e.getValue().authority()).orElse(null);
}
// Project creation/setup before opening a session is still a manual workflow.
return authority == null ? () -> {} : authority.get();
@@ -32,9 +32,12 @@ public final class DefaultProjectSessionFactory implements ProjectSessionFactory
final var setup = setupStore.load(project);
final var state = stateStore.load(project);
var automation = new DefaultAutomationSession(project.rootPath(), operations);
var registration = access.register(project.rootPath(), automation::enterManual);
var ready = new java.util.concurrent.atomic.AtomicBoolean();
var registration = access.register(project.rootPath(), automation::enterManual,
() -> ready.get() && !automation.snapshot().closed());
try { lsp.boot(project); }
catch (RuntimeException failure) { registration.unsubscribe(); throw failure; }
ready.set(true);
return new DefaultProjectSession(project, stateStore, setup, new DefaultExecutionSession(), lsp, state, automation, registration);
}
}
@@ -0,0 +1,47 @@
package p.studio.core.project;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import p.studio.api.automation.AutomationException;
import p.studio.api.automation.AutomationFailure;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.concurrent.atomic.AtomicBoolean;
import static org.junit.jupiter.api.Assertions.*;
class ProjectAccessRegistryTest {
@TempDir Path root;
@Test void exactOpenRootsIgnoreFocusAndDoNotAcquireManualAuthority() throws Exception {
var registry = new ProjectAccessRegistry();
Path first = Files.createDirectory(root.resolve("first")).toRealPath();
Path second = Files.createDirectory(root.resolve("second")).toRealPath();
var available = new AtomicBoolean(true);
var registration = registry.register(first, () -> { throw new AssertionError("Context does not acquire control"); }, available::get);
registry.register(second, () -> () -> {}, () -> true);
assertEquals(first, registry.requireOpenRoot(first));
assertEquals(second, registry.requireOpenRoot(second));
assertDenied(registry, first.resolve("src"));
assertDenied(registry, Path.of("relative"));
var alias = Files.createSymbolicLink(root.resolve("alias"), first);
assertEquals(first, registry.requireOpenRoot(alias));
available.set(false);
assertDenied(registry, first);
available.set(true);
registration.unsubscribe();
assertDenied(registry, first);
assertEquals(second, registry.requireOpenRoot(second));
}
@Test void guardOnlyRegistrationIsNotAnOpenProject() {
var registry = new ProjectAccessRegistry();
registry.register(root, () -> () -> {});
assertDenied(registry, root);
assertNotNull(registry.enterManual(root.resolve("src")));
}
private void assertDenied(ProjectAccessRegistry registry, Path path) {
assertEquals(AutomationFailure.Code.PROJECT_NOT_OPEN,
assertThrows(AutomationException.class, () -> registry.requireOpenRoot(path)).failure().code());
}
}
@@ -17,21 +17,24 @@ final class DefaultProjectSessionTest {
@TempDir Path temporaryDirectory;
@Test
void factoryLoadsStateBootsLspAndCloseIsOrderedAndIdempotent() {
void factoryLoadsStateBootsLspAndCloseIsOrderedAndIdempotent() throws Exception {
final var mapper = new ObjectMapper();
final var stateStore = new ProjectLocalStudioStateStore(mapper);
final var setupStore = new ProjectLocalStudioSetupStore(mapper);
final var lsp = new RecordingLsp();
final var access = new p.studio.core.project.ProjectAccessRegistry();
final var factory = new DefaultProjectSessionFactory(stateStore, setupStore, lsp,
new p.studio.core.project.ProjectAccessRegistry(), new p.studio.core.support.ControlledOperations());
access, new p.studio.core.support.ControlledOperations());
final var project = project();
final var session = factory.open(project);
assertEquals(project.rootPath().toRealPath(), access.requireOpenRoot(project.rootPath()));
final var next = ProjectLocalStudioState.defaults()
.withOpenShellState(new ProjectLocalStudioState.OpenShellState("DEBUG"));
session.replaceProjectLocalStudioState(next);
session.close();
session.close();
assertThrows(p.studio.api.automation.AutomationException.class, () -> access.requireOpenRoot(project.rootPath()));
assertEquals(1, lsp.boots);
assertEquals(1, lsp.shutdowns);
@@ -55,6 +58,25 @@ final class DefaultProjectSessionTest {
return new ProjectReference("Example", "1.0.0", "pbs", 1, ProjectTarget.Game, temporaryDirectory);
}
@Test
void failedBootNeverPublishesAnOpenProjectAndRemovesItsRegistration() {
var mapper = new ObjectMapper();
var access = new p.studio.core.project.ProjectAccessRegistry();
var lsp = new LspLifecyclePort() {
@Override public void boot(ProjectReference project) {
assertThrows(p.studio.api.automation.AutomationException.class, () -> access.requireOpenRoot(project.rootPath()));
throw new IllegalStateException("boot failed");
}
@Override public void shutdown(ProjectReference project) {}
};
var factory = new DefaultProjectSessionFactory(new ProjectLocalStudioStateStore(mapper),
new ProjectLocalStudioSetupStore(mapper), lsp, access, new p.studio.core.support.ControlledOperations());
assertThrows(IllegalStateException.class, () -> factory.open(project()));
assertThrows(p.studio.api.automation.AutomationException.class, () -> access.requireOpenRoot(project().rootPath()));
var registration = access.register(project().rootPath(), () -> () -> {}, () -> true);
registration.unsubscribe();
}
private static final class RecordingLsp implements LspLifecyclePort {
int boots;
int shutdowns;