@cratis/pi 7.28.1 → 7.29.1

package/README.md

@@ -29,6 +29,24 @@ yields to the managed installation to avoid duplicate resources and hooks. The P
 package manages only Pi; it neither configures other harnesses nor owns a local
 managed corpus.
 
+## Screenplay MCP tools
+
+The packaged `cratis-mcp` extension starts the Screenplay MCP server
+(`cratis screenplay mcp`) when the resolved profiles include `cratis/screenplay`.
+The backend application profiles compose it, so an application repository gets
+the Screenplay skills and, when the Cratis CLI 3.46.1 or later is installed, the
+Screenplay tools; the server creates no model folder until the first write.
+Installing them does not opt the repository in to model-first work.
+
+When Screenplay comes in only through such a profile and no model root is
+configured, a missing CLI, a CLI older than 3.46.1 (which creates the model
+folder at server start) or a server that fails to start leaves the Screenplay
+tools inactive with one informational notice when Pi has a UI, and silently otherwise.
+Selecting any profile that also reaches Screenplay without going through an application
+profile (including `cratis/screenplay`, `cratis/modeling/screenplay-stage`,
+`cratis/full/*` or `cratis`), or configuring `mcpServers.screenplay.root` in
+`.cratis/ai.json`, keeps startup failures visible as errors.
+
 ## Path guidance and subagents
 
 The packaged `cratis-path-guidance` extension attaches a path-scoped rule to the

package/package/corpus/harnesses/pi/extensions/cratis-mcp/configuration.ts

@@ -69,14 +69,21 @@ export function selectedServer(project: string, corpus: string) {
     });
     const languages = new Set(strings(configuration.languages));
     const selected = new Set<string>();
-    const select = (id: string, explicit: boolean): void => {
-        if (selected.has(id)) return;
+    const visited = new Set<string>();
+    let nonApplicationSelection = false;
+    const select = (id: string, explicit: boolean, throughApplication = false): void => {
         const profile = profiles.find(candidate => candidate.id === id);
         if (!profile) throw new Error(`Unknown Cratis AI profile '${id}'.`);
         const supported = strings(profile.languages);
         if (!explicit && supported.length && !supported.some(language => language === 'language-agnostic' || languages.has(language))) return;
+        const applicationPath = throughApplication || id === 'cratis/application' || id.startsWith('cratis/application/');
+        // Visit both paths: application composition must not hide an existing, independently selected Screenplay path.
+        const key = JSON.stringify([id, applicationPath]);
+        if (visited.has(key)) return;
+        visited.add(key);
         selected.add(id);
-        strings(profile.composes).forEach(child => select(child, false));
+        if (id === 'cratis/screenplay' && !applicationPath) nonApplicationSelection = true;
+        strings(profile.composes).forEach(child => select(child, false, applicationPath));
     };
     requested.forEach(id => select(id, true));
     if (!selected.has('cratis/screenplay')) return undefined;
@@ -99,5 +106,9 @@ export function selectedServer(project: string, corpus: string) {
     const root = object(screenplay) ? screenplay.root : undefined;
     if (root !== undefined && typeof root !== 'string') throw new Error('Screenplay MCP root must be a project-relative string.');
     const physicalProject = realpathSync(project);
-    return { project: physicalProject, root: root === undefined ? undefined : physicalRoot(physicalProject, root) };
+    return {
+        project: physicalProject,
+        root: root === undefined ? undefined : physicalRoot(physicalProject, root),
+        composedOnly: !nonApplicationSelection && root === undefined,
+    };
 }

package/package/corpus/harnesses/pi/extensions/cratis-mcp/index.ts

@@ -7,19 +7,22 @@ import { fileURLToPath } from 'node:url';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { ConnectionFailure } from './ConnectionFailure.ts';
 import { object, selectedServer } from './configuration.ts';
-import { startConnection } from './process.ts';
+import { startConnection, supportsNoModelStartup } from './process.ts';
 import { discover, failedResult, mapResult } from './protocol.ts';
+import type { DiscoveredTool } from './DiscoveredTool.ts';
 import type { StdioConnection } from './StdioConnection.ts';
 
 const extensionDirectory = dirname(fileURLToPath(import.meta.url));
 const bundledCorpus = resolve(extensionDirectory, '..', '..', '..', '..');
 
 /** Native tools go through Pi's tool_call restrictions and normal execution/result pipeline. */
-export function registerBridge(pi: ExtensionAPI, corpus: string, connect = startConnection): void {
+export function registerBridge(pi: ExtensionAPI, corpus: string, connect = startConnection, checkVersion = supportsNoModelStartup): void {
     let connection: StdioConnection | undefined;
     let selectionKey: string | undefined;
     let attempted = false;
     let uncertain = false;
+    let startupSupported: Promise<boolean> | undefined;
+    let unavailableReported = false;
     const registered = new Set<string>();
     const paused = new Set<string>();
     const failures = new Map<string, ReturnType<typeof failedResult>>();
@@ -47,6 +50,7 @@ export function registerBridge(pi: ExtensionAPI, corpus: string, connect = start
         if (!connection || connection.stopped) throw new Error('Screenplay connection is unavailable. No request was retried; explicitly reload after inspecting any uncertain mutation.');
     };
     const refresh = async (context: ExtensionContext, newSession = false): Promise<void> => {
+        if (newSession) { startupSupported = undefined; unavailableReported = false; }
         const previouslyActive = new Set([...pi.getActiveTools(), ...paused]);
         let selection: ReturnType<typeof selectedServer>;
         try { selection = currentSelection(context); }
@@ -60,11 +64,27 @@ export function registerBridge(pi: ExtensionAPI, corpus: string, connect = start
         if (!selection) return;
         if (uncertain) throw new Error('Screenplay mutation outcome remains unknown. Explicitly reload, inspect workspace-state, and obtain authorization before any recovery.');
         const modelRoot = selection.root ?? "the project's Screenplay model";
-        const activeConnection = connect(selection.project);
-        connection = activeConnection;
+        let activeConnection: StdioConnection;
+        let tools: DiscoveredTool[];
         try {
-            const tools = await discover(activeConnection);
+            if (selection.composedOnly && !await (startupSupported ??= checkVersion(selection.project))) {
+                throw new Error('Screenplay optional startup requires Cratis CLI 3.46.1 or later.');
+            }
+            activeConnection = connect(selection.project);
+            connection = activeConnection;
+            tools = await discover(activeConnection);
             if (connection !== activeConnection || activeConnection.stopped) throw new Error('Screenplay session ended during discovery.');
+        } catch (error) {
+            dispose();
+            // Application-only composition makes MCP optional. Independent profile/root errors and uncertain mutations still surface.
+            if (!selection.composedOnly || uncertain) throw error;
+            if (!unavailableReported) {
+                unavailableReported = true;
+                if (context.hasUI) context.ui.notify('Screenplay MCP is unavailable; install/update the Cratis CLI to 3.46.1 or later to enable it.', 'info');
+            }
+            return;
+        }
+        try {
             const existing = new Set(pi.getAllTools().map(tool => tool.name));
             if (tools.some(tool => existing.has(tool.nativeName) && !registered.has(tool.nativeName))) throw new Error('Screenplay native tool name conflicts with another extension.');
             const oldNames = new Set(registered);

package/package/corpus/harnesses/pi/extensions/cratis-mcp/process.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { StdioConnection } from './StdioConnection.ts';
 
 /** Preserve OS/runtime lookup only; never copy arbitrary credentials or descriptor environment values. */
@@ -13,6 +13,27 @@ export function childEnvironment(source: NodeJS.ProcessEnv = process.env): NodeJ
     return environment;
 }
 
+/** Older CLIs create a model root at server startup; optional composition must remain footprint-free. */
+export function supportsNoModelStartup(project: string, execute: typeof execFile = execFile): Promise<boolean> {
+    return new Promise(resolve => {
+        execute('cratis', ['--version'], {
+            cwd: project,
+            env: childEnvironment(),
+            shell: false,
+            windowsHide: true,
+            timeout: 3000,
+            killSignal: 'SIGKILL',
+            maxBuffer: 4096,
+            encoding: 'utf8',
+        }, (error, stdout) => {
+            const version = /^\s*(\d+)\.(\d+)\.(\d+)(?:\+[\w.-]+)?\s*$/.exec(stdout);
+            if (error || !version) { resolve(false); return; }
+            const [, major, minor, patch] = version.map(Number);
+            resolve(major > 3 || (major === 3 && (minor > 46 || (minor === 46 && patch >= 1))));
+        });
+    });
+}
+
 export function startConnection(project: string, launch: typeof spawn = spawn): StdioConnection {
     return new StdioConnection(launch('cratis', ['screenplay', 'mcp', '--project-root', project], {
         cwd: project,

package/package/corpus/rules/profiles.md

@@ -51,16 +51,21 @@ The complete list of available profiles is defined in [profile-catalog.json](../
 
 | Profile ID | Description | Automatically Includes |
 |---|---|---|
-| `cratis/application` | Full application stack (C# + React + TypeScript) | `cratis/application/csharp`, `cratis/application/elixir`, `cratis/application/kotlin`, `cratis/application/typescript`, `cratis/arc/core`, `cratis/arc/react`, `cratis/chronicle/core`, `cratis/components`, `cratis/fundamentals`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
-| `cratis/application/csharp` | C# backend with Arc + Chronicle | `cratis/arc`, `cratis/arc/react`, `cratis/chronicle`, `cratis/components`, `cratis/fundamentals`, `cratis/language/csharp`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
+| `cratis/application` | Full application stack (C# + React + TypeScript) | `cratis/application/csharp`, `cratis/application/elixir`, `cratis/application/java`, `cratis/application/kotlin`, `cratis/application/typescript`, `cratis/arc/core`, `cratis/arc/react`, `cratis/chronicle/core`, `cratis/components`, `cratis/fundamentals`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
+| `cratis/application/csharp` | C# backend with Arc + Chronicle | `cratis/arc`, `cratis/arc/react`, `cratis/chronicle`, `cratis/components`, `cratis/fundamentals`, `cratis/language/csharp`, `cratis/screenplay`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
 | `cratis/application/react` | React frontend with Cratis Components | `cratis/arc/core`, `cratis/arc/react`, `cratis/components`, `cratis/fundamentals`, `cratis/specifications/dotnet`, `cratis/specifications/typescript` |
-| `cratis/application/typescript` | TypeScript client for Chronicle | `cratis/chronicle/client-typescript`, `cratis/language/typescript`, `cratis/specifications/typescript` |
-| `cratis/application/arc-chronicle` | Arc + Chronicle integration | `cratis/arc/core`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
-| `cratis/application/arc-only` | Arc without Chronicle | `cratis/arc/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
-| `cratis/application/chronicle-dotnet` | Chronicle .NET client | `cratis/chronicle/client-dotnet`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/specifications/dotnet` |
-| `cratis/application/elixir` | Elixir Chronicle client | `cratis/chronicle/client-elixir`, `cratis/language/elixir` |
-| `cratis/application/kotlin` | Kotlin Arc + Chronicle application | `cratis/arc/client-kotlin`, `cratis/chronicle/client-kotlin`, `cratis/language/kotlin` |
-| `cratis/application/java` | Java Arc + Chronicle application | `cratis/arc/client-kotlin`, `cratis/chronicle/client-java`, `cratis/language/java` |
+| `cratis/application/typescript` | TypeScript client for Chronicle | `cratis/chronicle/client-typescript`, `cratis/language/typescript`, `cratis/screenplay`, `cratis/specifications/typescript` |
+| `cratis/application/arc-chronicle` | Arc + Chronicle integration | `cratis/arc/core`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/screenplay`, `cratis/specifications/dotnet` |
+| `cratis/application/arc-only` | Arc without Chronicle | `cratis/arc/core`, `cratis/fundamentals`, `cratis/screenplay`, `cratis/specifications/dotnet` |
+| `cratis/application/chronicle-dotnet` | Chronicle .NET client | `cratis/chronicle/client-dotnet`, `cratis/chronicle/core`, `cratis/fundamentals`, `cratis/screenplay`, `cratis/specifications/dotnet` |
+| `cratis/application/elixir` | Elixir Chronicle client | `cratis/chronicle/client-elixir`, `cratis/language/elixir`, `cratis/screenplay` |
+| `cratis/application/kotlin` | Kotlin Arc + Chronicle application | `cratis/arc/client-kotlin`, `cratis/chronicle/client-kotlin`, `cratis/language/kotlin`, `cratis/screenplay` |
+| `cratis/application/java` | Java Arc + Chronicle application | `cratis/arc/client-kotlin`, `cratis/chronicle/client-java`, `cratis/language/java`, `cratis/screenplay` |
+
+`cratis/application` inherits `cratis/screenplay` through its language-specific
+children. Backend-bearing application profiles include the method skills and MCP
+declaration, not `cratis/stage`; the frontend-only `cratis/application/react`
+profile includes neither Screenplay nor Stage.
 
 ### Framework Profiles
 
@@ -179,7 +184,8 @@ or gap-fill from its contract; never edit Stage-managed output or weaken protect
 Otherwise stay code-first; only the entry-point session may propose a model, at most once
 per session. Master definition: `cratis-screenplay-modeling-lifecycle`. Framework and non-opted-in brownfield work remain
 code-first; infrastructure, clients, adapters and code attachments stay in code.
-Application profiles do not automatically compose `cratis/screenplay`.
+Backend-bearing application profiles automatically compose `cratis/screenplay`;
+installing its skills or registering its MCP server is not model-first opt-in.
 
 `cratis/screenplay` carries the **method** and the **language**. Load the lifecycle
 and one phase skill, then the construct skill needed for syntax.
@@ -228,6 +234,15 @@ conflicts. The model is wherever the project keeps its `.play` files, else under
 `src/`, else in a `Screenplay/` folder at the repository root; never under `.cratis/`.
 Project-owned configuration can name a root explicitly.
 
+**No-model startup requires Cratis CLI 3.46.1 or later.** With
+`cratis screenplay mcp --project-root <project>`, that version resolves the root
+without creating it; discovery, startup and proposals leave no model folder, and
+the first `apply` write creates it. `cratis ai install` also creates no model
+folder unless the project configured a root. Older CLIs create the resolved model root at
+server startup (`Screenplay/` when no `.play` files, `Source/` or `src/` exist); upgrade before using the automatically selected MCP server in a
+repository without a model. In Pi, when every selected path to Screenplay goes through an application profile and no root is configured, a missing, older or unavailable CLI leaves its MCP tools inactive with one informational UI notice (none in headless mode); an independent non-application path to Screenplay or a configured root still surfaces startup errors. See the toolchain skill's
+[version reference](../skills/cratis-screenplay-toolchain/references/versions.md).
+
 ## How to Use Profiles
 
 ### 1. Select Your Profile
@@ -268,7 +283,7 @@ Profiles can compose other profiles. When you select a parent profile, all child
 {
   "schemaVersion": "1.0.0",
   "profiles": [
-    "cratis/application/csharp"  // Includes: arc, arc/react, chronicle, components, fundamentals, language/csharp, specifications/dotnet, specifications/typescript
+    "cratis/application/csharp"  // Includes: arc, arc/react, chronicle, components, fundamentals, language/csharp, screenplay, specifications/dotnet, specifications/typescript
   ]
 }
 ```

package/package/corpus/skills/cratis-screenplay-toolchain/references/versions.md

@@ -31,6 +31,17 @@ Check the actual executable before relying on this table: `screenplay --version`
 `cratis --version`, MCP `initialize` → `serverInfo.version`. An older executable
 on PATH can shadow a newer install; inspect `which -a cratis`.
 
+**Minimum for no-model MCP startup: Cratis CLI 3.46.1.** At `v3.46.1`,
+`cratis screenplay mcp --project-root <project>` resolves a root without creating
+it; startup, discovery and proposals leave no model folder, and the first
+`apply` write creates it. `cratis ai install` creates no model folder unless a
+root is configured. Older CLIs create the resolved root on server startup (`Screenplay/` when no `.play` files, `Source/` or `src/` exist). Released
+source evidence: CLI
+`Source/Cli.Specs/for_ScreenplayMcpInvocation/when_serving_a_project_without_a_model/and_the_client_writes_a_document.cs`
+and `Source/Cli.Specs/for_AiMcpRegistration/when_installing/with_a_composed_profile.cs`
+at tag `v3.46.1` (CLI#322 / CLI#311). This minimum does not re-label the compiler
+or renderer probes below as results from the newer bundle.
+
 ## Two compilers, one rule
 
 Standalone Screenplay 4.131.0 and the CLI's 4.130.0 bundle are different releases.

package/package/profile-catalog.json

@@ -114,6 +114,7 @@
         "cratis/arc/core",
         "cratis/chronicle/core",
         "cratis/fundamentals",
+        "cratis/screenplay",
         "cratis/specifications/dotnet"
       ],
       "languages": [
@@ -125,6 +126,7 @@
       "composes": [
         "cratis/arc/core",
         "cratis/fundamentals",
+        "cratis/screenplay",
         "cratis/specifications/dotnet"
       ],
       "languages": [
@@ -137,6 +139,7 @@
         "cratis/chronicle/client-dotnet",
         "cratis/chronicle/core",
         "cratis/fundamentals",
+        "cratis/screenplay",
         "cratis/specifications/dotnet"
       ],
       "languages": [
@@ -152,6 +155,7 @@
         "cratis/components",
         "cratis/fundamentals",
         "cratis/language/csharp",
+        "cratis/screenplay",
         "cratis/specifications/dotnet",
         "cratis/specifications/typescript"
       ],
@@ -165,7 +169,8 @@
       "id": "cratis/application/elixir",
       "composes": [
         "cratis/chronicle/client-elixir",
-        "cratis/language/elixir"
+        "cratis/language/elixir",
+        "cratis/screenplay"
       ],
       "languages": [
         "elixir"
@@ -176,7 +181,8 @@
       "composes": [
         "cratis/arc/client-kotlin",
         "cratis/chronicle/client-java",
-        "cratis/language/java"
+        "cratis/language/java",
+        "cratis/screenplay"
       ],
       "languages": [
         "java"
@@ -187,7 +193,8 @@
       "composes": [
         "cratis/arc/client-kotlin",
         "cratis/chronicle/client-kotlin",
-        "cratis/language/kotlin"
+        "cratis/language/kotlin",
+        "cratis/screenplay"
       ],
       "languages": [
         "kotlin"
@@ -214,6 +221,7 @@
       "composes": [
         "cratis/chronicle/client-typescript",
         "cratis/language/typescript",
+        "cratis/screenplay",
         "cratis/specifications/typescript"
       ],
       "languages": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.28.1",
+  "version": "7.29.1",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [