create-caspian-app 0.2.0-beta.34 → 0.2.0-beta.36

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

@@ -7,12 +7,19 @@
 
 - Use this source-of-truth order: app runtime and app-owned code first, installed `casp` runtime second, packaged markdown docs third.
 - 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.
 - For current repo behavior, trust `main.py`, `src/lib/**`, `public/js/**`, `prisma/**`, and `src/app/**` over generic Caspian docs.
 - For framework internals, trust `.venv/Lib/site-packages/casp/**` over generic or older upstream guidance.
 - When docs and runtime disagree, align the docs to the code that actually runs in this workspace.
 - When `prisma/schema.prisma` changes, follow this order: run `npx prisma migrate dev`; if the change affects seed flow or `prisma/seed.ts`, run `npx prisma generate` and then `npx prisma db seed`; then run `npx ppy generate` so the Python ORM stays aligned with the schema.
 - Reuse the existing Python database layer in `src/lib/prisma/**`; do not create a second app-owned database abstraction unless the user explicitly asks for one.
 - Treat `src/lib/prisma/__init__.py`, `src/lib/prisma/db.py`, `src/lib/prisma/models.py`, and `settings/prisma-schema.json` as generated outputs owned by `npx ppy generate`; do not create or hand-edit them manually.
+- Treat `package.json` scripts as opt-in operations. Do not run `npm run dev`, `npm run build`, or other npm scripts unless the user explicitly asks, the task genuinely requires that exact script, or deployment preparation needs `npm run build`.
+- Use `npm run build` for deployment prep or an explicit build request, not as the default validation step for routine route, feature, or documentation edits.
+- Let the running dev stack own generated outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files. Treat those as generated artifacts rather than authored source.
+- Never treat `__pycache__/` directories or `.pyc` files as files to edit, regenerate on purpose, or keep in the final diff.
+- Treat `settings/component-map.json` and `settings/files-list.json` as generated outputs owned by `settings/component-map.ts` and `settings/files-list.ts`; inspect them when needed, but do not hand-edit them.
 - When `caspian.config.json` has `mcp: true`, treat `src/lib/mcp/mcp_server.py` as the app-owned FastMCP server and `src/lib/mcp/fastmcp.json` as the default MCP config. Use `npm run mcp` or `fastmcp run src/lib/mcp/fastmcp.json`; do not assume root `fastmcp.json` auto-discovery.
 - Keep auth policy in `src/lib/auth/auth_config.py` and keep auth bootstrap, middleware wiring, and provider registration in `main.py`.
 - In app-owned starter config like this workspace, routes start public because `src/lib/auth/auth_config.py` sets `is_all_routes_private=False` by default.
@@ -41,7 +48,7 @@
 
 - Keep `src/lib/` for app-owned shared code, service wrappers, and reusable helpers.
 - 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.
-- 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.
+- 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`.
 
 ### `public/js/main.js`
@@ -90,10 +97,14 @@
   3.  the markdown file being edited
 - Keep repo-specific facts accurate when they matter:
   - `caspian.config.json` is the first config file to read for enabled workspace features and scan directories
+  - `caspian.config.json` is the single source of truth for whether an optional feature is enabled in the current workspace
   - this workspace already has `src/lib/prisma/**`
-  - this workspace's app-owned FastMCP server lives in `src/lib/mcp/mcp_server.py`
-  - the default FastMCP config lives in `src/lib/mcp/fastmcp.json`
-  - `package.json` starts MCP through `npm run mcp`, which runs `settings/restart-mcp.ts`; manual FastMCP runs should pass the explicit nested config path because root auto-discovery does not find it
+  - this workspace currently has `mcp: false` in `caspian.config.json`, so do not assume `src/lib/mcp/**`, `settings/restart-mcp.ts`, or `npm run mcp` exist until MCP is explicitly enabled
+  - `package.json` currently defines `projectName`, `tailwind`, `tailwind:build`, `browserSync`, `browserSync:build`, `dev`, and `build`
+  - if a feature flag is false and the user wants that feature, ask before enabling it, then update `caspian.config.json` and use `npx casp update project` to refresh framework-managed files
+  - do not run `package.json` scripts by default for ordinary source edits; only use them when the user explicitly asks, the task requires them, or deployment prep needs `npm run build`
+  - `npm run dev` is a long-running local stack command that can regenerate `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` artifacts; those are generated outputs, not authored source files
+  - `settings/component-map.ts` and `settings/files-list.ts` own `settings/component-map.json` and `settings/files-list.json`; inspect the JSON when needed, but let the framework regenerate it instead of editing it by hand
   - auth policy lives in `src/lib/auth/auth_config.py`
   - the app-owned starter config in this workspace begins public-first with `is_all_routes_private=False`, so treat routes as public by default unless the app explicitly switches to all-private mode
   - choose all-private mode in `src/lib/auth/auth_config.py` only when public routes are the minority; otherwise keep mixed mode and maintain `private_routes`

package/dist/AGENTS.md

@@ -30,6 +30,8 @@ If docs differ from either of those, update the docs to match the code that actu
 
 Before making feature, tooling, or scaffolding decisions, read `caspian.config.json` almost immediately. 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 an optional Caspian feature is enabled in the current workspace. Use feature-specific docs 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 follow the Caspian update workflow to refresh framework-managed files.
+
 ## Verified Workspace Facts
 
 - Local Caspian docs live under `node_modules/caspian-utils/dist/docs/`.
@@ -45,17 +47,19 @@ Before making feature, tooling, or scaffolding decisions, read `caspian.config.j
 - Prefer logout via auth-protected RPC from page-level or component-level UI: `pp.rpc("signout")` backed by `@rpc(require_auth=True)`. Use a dedicated signout route only for plain form POST or no-JavaScript edge cases.
 - Protect customized `src/lib/auth/auth_config.py` from framework updates by adding `./src/lib/auth/auth_config.py` to `excludeFiles` in `caspian.config.json`.
 - This workspace already has an app-owned Python database layer in `src/lib/prisma/`.
-- This workspace now has an app-owned FastMCP server at `src/lib/mcp/mcp_server.py`, with `src/lib/mcp/fastmcp.json` as the default MCP server spec.
-- `package.json` starts MCP through `npm run mcp`, which runs `settings/restart-mcp.ts` and prefers `src/lib/mcp/fastmcp.json` before legacy root configs. Direct FastMCP runs should pass the explicit nested config path.
+- This workspace currently has `mcp: false` in `caspian.config.json`, so do not assume `src/lib/mcp/**`, `settings/restart-mcp.ts`, or `npm run mcp` exist unless MCP is explicitly enabled later.
+- `package.json` currently defines `projectName`, `tailwind`, `tailwind:build`, `browserSync`, `browserSync:build`, `dev`, and `build`. Treat those scripts as opt-in operational commands, not default validation steps for ordinary source edits.
 - Reuse `src/lib/prisma/prisma`, `PrismaClient`, generated models, and helper types instead of creating a second Python database abstraction.
 - Prisma schema source of truth is `prisma/schema.prisma`.
 - 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: true`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+- `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"]`.
 - 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.
 - Route and component HTML templates must keep exactly one top-level lowercase HTML element so Caspian can inject `pp-component`. Think React-style single parent wrapper: good `<div>...</div>` with any owned script inside that same root, bad sibling top-level tags such as `<div>...</div><script ...></script>`.
+- When `npm run dev` is intentionally running, let that long-running stack own generated outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files. Treat those as generated artifacts, not authored source.
+- `settings/component-map.json` and `settings/files-list.json` are generated by `settings/component-map.ts` and `settings/files-list.ts` through the dev and build pipelines. Analyze them when needed, but do not hand-edit them.
 - In the current router inside `main.py`, path params are passed to `page()` as the first positional `dict` argument.
 - Matching query params can still be injected by name, and `request` is injected by keyword when declared.
 - The installed `casp.layout` runtime calls `layout()` synchronously. Keep async I/O in `page()` or `@rpc()`.
@@ -86,6 +90,12 @@ Use this map before making changes.
 - Keep app-owned shared code in `src/lib/**`.
 - Keep route-specific logic in `src/app/**`.
 - 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.
+- Do not run `package.json` scripts unless the user explicitly asks for them, the task genuinely requires that exact script, or deployment preparation needs `npm run build`.
+- Use `npm run build` for deployment prep or an explicit build request, not as the default validation step for routine route, feature, or documentation edits.
+- Never treat `__pycache__/` directories or `.pyc` files as authored source. Do not edit them manually and do not leave them in the final diff if a tool run creates them.
+- Never hand-edit `settings/component-map.json` or `settings/files-list.json`. Inspect them if needed, but let the framework regeneration flow update them.
 - Treat `.venv/Lib/site-packages/casp/**` as framework internals unless the task is explicitly about Caspian core behavior or installed-runtime documentation.
 - When a task involves Python-side database access, reuse `src/lib/prisma/**` instead of introducing a parallel helper, but do not hand-edit generated files in that directory.
 - When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first. If seed flow or `prisma/seed.ts` is involved, run `npx prisma generate` and then `npx prisma db seed`. After that, run `npx ppy generate` so the Python ORM layer and `settings/prisma-schema.json` stay aligned.
@@ -111,9 +121,11 @@ Use this map before making changes.
 The packaged docs in this workspace are already mostly aligned with the installed runtime, but keep these repo-specific clarifications in mind:
 
 - `database.md` is the source doc for the Prisma and Python ORM workflow in this repo: schema changes go through `npx prisma migrate dev`, optional `npx prisma generate` plus `npx prisma db seed`, then `npx ppy generate`, and generated ORM files under `src/lib/prisma/` plus `settings/prisma-schema.json` are not hand-edited.
-- `mcp.md` is the source doc for the nested FastMCP config path, the app-owned MCP server location, direct FastMCP command usage, and the workspace runner discovery order.
+- `mcp.md` is the source doc for MCP-enabled workspaces, but in this workspace `caspian.config.json` currently has `mcp: false`, so do not assume `src/lib/mcp/**` or `npm run mcp` exist until MCP is explicitly enabled.
+- Feature-specific docs are conditional on `caspian.config.json`: use `database.md` only when `prisma: true`, use `mcp.md` only when `mcp: true`, and treat disabled-feature docs as reference material until the user chooses to enable that feature.
 - `auth.md` is the source doc for auth routing guidance: choose all-private mode only when public routes are the minority, keep auth policy in `src/lib/auth/auth_config.py`, protect that file with `excludeFiles` if customized, prefer auth-protected RPC logout from page or component UI, and keep dedicated signout routes for form-post or no-JavaScript fallbacks.
 - `state.md` is correct to warn that cross-request persistence depends on `request.state.session`, which is not bridged in the current `main.py`.
+- `commands.md`, `installation.md`, and `project-structure.md` are the source docs for this repo's package-script guardrails: do not auto-run npm scripts for ordinary edits, use `npm run build` only for deployment prep or explicit build requests, and treat `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files as generated artifacts.
 - `routing.md`, `components.md`, `auth.md`, `fetch-data.md`, `cache.md`, `pulsepoint.md`, and `validation.md` should continue to be validated against the installed `casp` package before any behavior claims are changed.
 
 ## Maintenance Checklist

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.34",
+  "version": "0.2.0-beta.36",
   "description": "Scaffold a new Caspian project (FastAPI-powered reactive Python framework).",
   "main": "dist/index.js",
   "type": "module",