create-caspian-app 0.2.0-beta.35 → 0.2.0-beta.37

package/dist/.github/copilot-instructions.md

@@ -6,6 +6,7 @@
 ## Global Rules
 
 - Use this source-of-truth order: app runtime and app-owned code first, installed `casp` runtime second, packaged markdown docs third.
+- As the app grows, prefer `src/components/` for reusable application UI and reserve `src/lib/` for reusable non-UI code such as services, validators, adapters, and shared helpers.
 - Read `./caspian.config.json` almost immediately before making feature, tooling, scaffolding, or file-placement decisions. Treat it as the workspace feature gate for flags such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, and `componentScanDirs`.
 - Treat `caspian.config.json` as the single source of truth for whether optional Caspian features are enabled in the current workspace. Use feature-specific docs, files, and commands only after the matching flag is confirmed as enabled.
 - If a feature is disabled and the user wants it, ask whether they want to enable it first, then update `caspian.config.json` and follow `npx casp update project` so framework-managed files align with the new feature set.
@@ -46,11 +47,18 @@
 
 ### `src/lib/**/*.py`
 
-- Keep `src/lib/` for app-owned shared code, service wrappers, and reusable helpers.
+- Keep `src/lib/` for app-owned shared non-UI code, service wrappers, validators, adapters, and reusable helpers.
+- Prefer `src/components/` for reusable rendered UI instead of placing component modules in `src/lib/`.
 - Reuse the generated `src/lib/prisma/` package for Python database access, but do not hand-edit files under `src/lib/prisma/`; regenerate them with `npx ppy generate` after schema changes.
 - When `caspian.config.json` has `mcp: true`, keep app-owned MCP tools in `src/lib/mcp/mcp_server.py` and keep the default FastMCP config in `src/lib/mcp/fastmcp.json`. If those locations change, update `settings/restart-mcp.ts` and the MCP docs together.
 - Keep auth policy in `src/lib/auth/auth_config.py`. Keep auth bootstrap and middleware order changes in `main.py`.
 
+### `src/components/**/*.py`
+
+- Keep `src/components/` as the default home for reusable application UI components.
+- Move shared cards, forms, shells, navigation, and other reusable rendered building blocks here once they are used across routes or features.
+- Keep route-owned markup in `src/app/**`, and keep non-UI helpers or services in `src/lib/**`.
+
 ### `public/js/main.js`
 
 - Treat `public/js/main.js` as the thin browser bootstrap entry point.

package/dist/AGENTS.md

@@ -54,6 +54,7 @@ Treat `caspian.config.json` as the single source of truth for whether an optiona
 - The schema-change workflow in this workspace is: `npx prisma migrate dev`; if seed flow or `prisma/seed.ts` is involved, run `npx prisma generate` and then `npx prisma db seed`; then run `npx ppy generate`.
 - `npx ppy generate` owns `src/lib/prisma/__init__.py`, `src/lib/prisma/db.py`, `src/lib/prisma/models.py`, and `settings/prisma-schema.json`; do not hand-edit those generated files.
 - `caspian.config.json` is the first config file to check for enabled workspace features. In the current workspace it sets `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+- As the app grows, prefer `src/components/` for reusable rendered UI and `src/lib/` for reusable non-UI support code.
 - PulsePoint runtime code is shipped in `public/js/pp-reactive-v2.js` and loaded from `public/js/main.js`.
 - `pp-component` is injected by the Python render pipeline onto page, layout, and component roots; authored route and component templates should not add it manually.
 - `main.py` runs `transform_scripts(...)`, so authored body `<script>` tags are rewritten to `<script type="text/pp">` in rendered HTML; route, layout, and component templates should write plain `<script>` in source.
@@ -88,7 +89,9 @@ Use this map before making changes.
 ## Editing Rules
 
 - Keep app-owned shared code in `src/lib/**`.
+- Keep reusable application UI components in `src/components/**`.
 - Keep route-specific logic in `src/app/**`.
+- When deciding between `src/components/**` and `src/lib/**`, put reusable rendered UI in `src/components/**` and put services, validators, adapters, database helpers, and other non-UI support code in `src/lib/**`.
 - Read `caspian.config.json` before deciding whether a Caspian feature should be used, documented, scaffolded, or avoided in the current workspace.
 - Treat `caspian.config.json` as the single source of truth for optional features. Do not use feature-specific files, commands, or docs until the corresponding flag is enabled.
 - If a feature flag is false and the user wants that feature, ask for confirmation first, then update `caspian.config.json` and run `npx casp update project` so framework-managed files align with the new feature set.

package/dist/settings/bs-config.ts

@@ -13,6 +13,7 @@ import { componentMap } from "./component-map.js";
 import { createServer } from "net";
 import chalk from "chalk";
 import { networkInterfaces } from "os";
+import caspianConfig from "../caspian.config.json";
 
 const { __dirname } = getFileMeta();
 const bs: BrowserSyncInstance = browserSync.create();
@@ -24,14 +25,48 @@ let lastChangedFile: string | null = null;
 let pythonPort = 0;
 let bsPort = 0;
 
-function getAvailablePort(startPort: number): Promise<number> {
+function getReservedPorts(): Set<number> {
+  const reservedPorts = new Set<number>();
+
+  if (!caspianConfig.mcp) {
+    return reservedPorts;
+  }
+
+  const mcpSpecPath = join(__dirname, "..", "src", "lib", "mcp", "fastmcp.json");
+  if (!existsSync(mcpSpecPath)) {
+    return reservedPorts;
+  }
+
+  try {
+    const mcpSpec = JSON.parse(readFileSync(mcpSpecPath, "utf-8"));
+    const reservedPort = Number(mcpSpec?.deployment?.port);
+
+    if (Number.isInteger(reservedPort) && reservedPort > 0) {
+      reservedPorts.add(reservedPort);
+    }
+  } catch {
+    // Ignore malformed local MCP config and fall back to dynamic allocation.
+  }
+
+  return reservedPorts;
+}
+
+function getAvailablePort(
+  startPort: number,
+  reservedPorts: Set<number> = new Set(),
+): Promise<number> {
   return new Promise((resolve) => {
+    if (reservedPorts.has(startPort)) {
+      resolve(getAvailablePort(startPort + 1, reservedPorts));
+      return;
+    }
+
     const server = createServer();
     server.listen(startPort, () => {
       server.close(() => resolve(startPort));
     });
     server.on("error", () => {
-      resolve(getAvailablePort(startPort + 1));
+      resolve(getAvailablePort(startPort + 1, reservedPorts));
     });
   });
 }
@@ -134,8 +169,10 @@ const publicPipeline = new DebouncedWorker(
 );
 
 (async () => {
-  bsPort = await getAvailablePort(5090);
-  pythonPort = await getAvailablePort(bsPort + 10);
+  const reservedPorts = getReservedPorts();
+
+  bsPort = await getAvailablePort(5090, reservedPorts);
+  pythonPort = await getAvailablePort(5200, reservedPorts);
 
   updateRouteFilesCache();
 

package/dist/settings/restart-mcp.ts

@@ -1,5 +1,6 @@
-import { existsSync } from "fs";
-import { join } from "path";
+import { existsSync, readFileSync } from "fs";
+import { isAbsolute, join } from "path";
+import { createServer } from "net";
 import caspianConfig from "../caspian.config.json";
 import { createRestartableProcess, onExit } from "./utils.js";
 
@@ -36,11 +37,79 @@ function getServerSpec(): string | null {
   return null;
 }
 
-function buildArgs(serverSpec: string): string[] {
+function getServerSpecPath(serverSpec: string): string | null {
+  if (serverSpec.startsWith("http://") || serverSpec.startsWith("https://")) {
+    return null;
+  }
+
+  return isAbsolute(serverSpec) ? serverSpec : join(projectRoot, serverSpec);
+}
+
+function readDeploymentConfig(serverSpec: string): Record<string, unknown> {
+  const serverSpecPath = getServerSpecPath(serverSpec);
+  if (!serverSpecPath || !existsSync(serverSpecPath)) {
+    return {};
+  }
+
+  try {
+    const rawConfig = JSON.parse(readFileSync(serverSpecPath, "utf-8"));
+    if (rawConfig && typeof rawConfig === "object") {
+      const deployment = rawConfig.deployment;
+      if (deployment && typeof deployment === "object") {
+        return deployment as Record<string, unknown>;
+      }
+    }
+  } catch {
+    // Ignore malformed specs and allow FastMCP to validate them.
+  }
+
+  return {};
+}
+
+function getPreferredHost(serverSpec: string): string {
+  return (
+    process.env.MCP_HOST?.trim() ||
+    String(readDeploymentConfig(serverSpec).host || "").trim() ||
+    "127.0.0.1"
+  );
+}
+
+function getPreferredPort(serverSpec: string): number | null {
+  const rawPort =
+    process.env.MCP_PORT?.trim() ||
+    String(readDeploymentConfig(serverSpec).port || "").trim();
+
+  if (!rawPort) {
+    return null;
+  }
+
+  const port = Number(rawPort);
+  if (!Number.isInteger(port) || port <= 0) {
+    return null;
+  }
+
+  return port;
+}
+
+function findAvailablePort(startPort: number, host: string): Promise<number> {
+  return new Promise((resolve) => {
+    const server = createServer();
+
+    server.listen(startPort, host, () => {
+      server.close(() => resolve(startPort));
+    });
+
+    server.on("error", () => {
+      resolve(findAvailablePort(startPort + 1, host));
+    });
+  });
+}
+
+function buildArgs(serverSpec: string, portOverride?: string): string[] {
   const args = ["run", serverSpec, "--no-banner"];
   const transport = process.env.MCP_TRANSPORT?.trim();
   const host = process.env.MCP_HOST?.trim();
-  const port = process.env.MCP_PORT?.trim();
+  const port = portOverride || process.env.MCP_PORT?.trim();
   const path = process.env.MCP_PATH?.trim();
   const logLevel = process.env.MCP_LOG_LEVEL?.trim();
 
@@ -133,12 +202,24 @@ if (!serverSpec) {
   process.exit(0);
 }
 
+const preferredHost = getPreferredHost(serverSpec);
+const preferredPort = getPreferredPort(serverSpec);
+const resolvedPort = preferredPort
+  ? await findAvailablePort(preferredPort, preferredHost)
+  : null;
+
+if (preferredPort && resolvedPort && preferredPort !== resolvedPort) {
+  console.log(
+    `[mcp] Port ${preferredPort} is unavailable on ${preferredHost}, using ${resolvedPort} instead.`,
+  );
+}
+
 const handleMcpOutput = createMcpOutputHandler();
 
 const runner = createRestartableProcess({
   name: "mcp",
   cmd: fastMcpCommand,
-  args: buildArgs(serverSpec),
+  args: buildArgs(serverSpec, resolvedPort ? String(resolvedPort) : undefined),
   startMessage: "[mcp] Starting MCP server...",
   onStdout: createLineHandler(handleMcpOutput),
   onStderr: createLineHandler(handleMcpOutput),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-caspian-app",
-  "version": "0.2.0-beta.35",
+  "version": "0.2.0-beta.37",
   "description": "Scaffold a new Caspian project (FastAPI-powered reactive Python framework).",
   "main": "dist/index.js",
   "type": "module",