@jskit-ai/create-app 0.1.93 → 0.1.95

package/templates/minimal-shell/packages/main/package.descriptor.mjs

@@ -0,0 +1,69 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@local/main",
+  version: "0.1.0",
+  kind: "runtime",
+  description: "App-local main composition and glue scaffold.",
+  dependsOn: [],
+  capabilities: {
+    provides: [],
+    requires: []
+  },
+  options: {},
+  runtime: {
+    server: {
+      providerEntrypoint: "src/server/MainServiceProvider.js",
+      providers: [
+        {
+          entrypoint: "src/server/MainServiceProvider.js",
+          export: "MainServiceProvider"
+        }
+      ]
+    },
+    client: {
+      providers: [
+        {
+          entrypoint: "src/client/providers/MainClientProvider.js",
+          export: "MainClientProvider"
+        }
+      ]
+    }
+  },
+  metadata: {
+    jskit: {
+      ownershipGuidance: {
+        title: "App-local main lane",
+        summary: "Keep @local/main focused on app composition and lightweight glue. Substantial server features should become dedicated packages instead of growing inside packages/main.",
+        responsibilities: [
+          "packages/main server code: bootstraps app-local configuration and lightweight wiring only",
+          "substantial non-CRUD server features: scaffold a dedicated package with feature-server-generator",
+          "packages/main: do not add service/controller/route/repository feature trees here"
+        ],
+        examples: [
+          "jskit generate feature-server-generator scaffold booking-engine",
+          "jskit generate feature-server-generator scaffold availability-engine --mode orchestrator"
+        ]
+      }
+    },
+    server: {
+      routes: []
+    },
+    ui: {
+      routes: [],
+      elements: [],
+      overrides: []
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {},
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    text: [],
+    files: []
+  }
+});

package/templates/minimal-shell/packages/main/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@local/main",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./client": "./src/client/index.js",
+    "./server": "./src/server/index.js",
+    "./server/MainServiceProvider": "./src/server/MainServiceProvider.js",
+    "./shared": "./src/shared/index.js"
+  }
+}

package/templates/minimal-shell/packages/main/src/client/index.js

@@ -0,0 +1,13 @@
+/**
+ * Client entrypoint for @local/main.
+ *
+ * Export browser-facing modules from here.
+ *
+ * Example:
+ * export { MainClientProvider } from "./providers/MainClientProvider.js";
+ * export { registerMainClientComponent } from "./providers/MainClientProvider.js";
+ */
+export {
+  MainClientProvider,
+  registerMainClientComponent
+} from "./providers/MainClientProvider.js";

package/templates/minimal-shell/packages/main/src/client/providers/MainClientProvider.js

@@ -0,0 +1,20 @@
+const mainClientComponents = [];
+
+function registerMainClientComponent(token, resolveComponent) {
+  mainClientComponents.push({ token, resolveComponent });
+}
+
+class MainClientProvider {
+  static id = "local.main.client";
+
+  register(app) {
+    for (const { token, resolveComponent } of mainClientComponents) {
+      app.singleton(token, resolveComponent);
+    }
+  }
+}
+
+export {
+  MainClientProvider,
+  registerMainClientComponent
+};

package/templates/minimal-shell/packages/main/src/server/MainServiceProvider.js

@@ -0,0 +1,20 @@
+import { loadAppConfig } from "./loadAppConfig.js";
+
+class MainServiceProvider {
+  static id = "local.main";
+
+  // Register only lightweight app-local composition bindings here.
+  async register(app) {
+    const appConfig = await loadAppConfig({
+      moduleUrl: import.meta.url
+    });
+    app.instance("appConfig", appConfig);
+  }
+
+  // Keep packages/main as app glue only.
+  // When backend behavior becomes substantial, scaffold a dedicated package:
+  //   jskit generate feature-server-generator scaffold <feature-name>
+  boot() {}
+}
+
+export { MainServiceProvider };

package/templates/minimal-shell/packages/main/src/server/index.js

@@ -0,0 +1 @@
+export { MainServiceProvider } from "./MainServiceProvider.js";

package/templates/minimal-shell/packages/main/src/server/loadAppConfig.js

@@ -0,0 +1,9 @@
+import { loadAppConfigFromModuleUrl } from "@jskit-ai/kernel/server/support";
+
+async function loadAppConfig({ moduleUrl = import.meta.url } = {}) {
+  return loadAppConfigFromModuleUrl({
+    moduleUrl
+  });
+}
+
+export { loadAppConfig };

package/templates/minimal-shell/packages/main/src/shared/index.js

@@ -0,0 +1,10 @@
+/**
+ * Shared entrypoint for code used by both client and server.
+ *
+ * Keep this for genuinely app-local shared glue only.
+ *
+ * Example:
+ * export * from "./schemas/index.js";
+ * export * from "./constants/index.js";
+ */
+export {};

package/templates/minimal-shell/packages/main/src/shared/schemas/index.js

@@ -0,0 +1,22 @@
+/**
+ * App-local shared transport validators/resources live here.
+ * Dedicated feature packages should keep their own schemas with the feature.
+ *
+ * Example:
+ * import { createSchema } from "json-rest-schema";
+ *
+ * export const helloQuerySchema = createSchema({
+ *   name: { type: "string", minLength: 1, maxLength: 80 }
+ * });
+ *
+ * export const helloResponseSchema = {
+ *   type: "object",
+ *   additionalProperties: false,
+ *   required: ["ok", "message"],
+ *   properties: {
+ *     ok: { type: "boolean" },
+ *     message: { type: "string", minLength: 1 }
+ *   }
+ * };
+ */
+export {};

package/templates/minimal-shell/scripts/dokku-set-remote-envs-via-ssh.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/dokku-set-remote-envs-via-ssh.sh <ssh-target> <public-host>
+
+Reads the allowlisted deploy env vars from .env, derives APP_PUBLIC_URL from
+the public host, and pushes them to the remote Dokku app with --no-restart.
+
+Examples:
+  scripts/dokku-set-remote-envs-via-ssh.sh dokku@example.com beepollen.appgenius.biz
+  scripts/dokku-set-remote-envs-via-ssh.sh dokku@example.com https://beepollen.appgenius.biz
+EOF
+}
+
+die() {
+  printf 'Error: %s\n' "$*" >&2
+  exit 1
+}
+
+require_cmd() {
+  command -v "$1" >/dev/null 2>&1 || die "Required command not found: $1"
+}
+
+resolve_script_dir() {
+  cd -- "$(dirname -- "$0")" && pwd
+}
+
+if [[ $# -eq 0 ]]; then
+  usage
+  exit 1
+fi
+
+case "${1:-}" in
+  -h|--help)
+    usage
+    exit 0
+    ;;
+esac
+
+if [[ $# -ne 2 ]]; then
+  usage
+  exit 1
+fi
+
+require_cmd ssh
+require_cmd node
+
+SSH_TARGET="$1"
+PUBLIC_HOST_INPUT="$2"
+SCRIPT_DIR="$(resolve_script_dir)"
+APP_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd)"
+
+case "$PUBLIC_HOST_INPUT" in
+  http://*|https://*)
+    APP_PUBLIC_URL="$PUBLIC_HOST_INPUT"
+    ;;
+  *)
+    APP_PUBLIC_URL="https://${PUBLIC_HOST_INPUT}"
+    ;;
+esac
+
+APP_NAME="$(node - "$APP_ROOT" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+
+const appRoot = process.argv[2];
+
+function readNameFromJson(relativePath) {
+  const absolutePath = path.join(appRoot, relativePath);
+  if (!fs.existsSync(absolutePath)) {
+    return "";
+  }
+  const source = JSON.parse(fs.readFileSync(absolutePath, "utf8"));
+  return String(source?.name || "").trim();
+}
+
+const appName = readNameFromJson("app.json") || readNameFromJson("package.json");
+if (!appName) {
+  console.error("Unable to resolve app name from app.json or package.json.");
+  process.exit(1);
+}
+
+process.stdout.write(appName);
+NODE
+)"
+
+set_remote_env() {
+  local key="$1"
+  local encoded_value="$2"
+
+  ssh "$SSH_TARGET" /bin/bash -s -- "$APP_NAME" "$key" "$encoded_value" <<'EOF'
+set -Eeuo pipefail
+
+APP_NAME="$1"
+KEY="$2"
+ENCODED_VALUE="$3"
+
+command -v dokku >/dev/null 2>&1 || {
+  printf 'dokku command not found on remote host.\n' >&2
+  exit 1
+}
+
+dokku config:set --no-restart --encoded "$APP_NAME" "$KEY=$ENCODED_VALUE" >/dev/null
+EOF
+}
+
+while IFS=$'\t' read -r key encoded_value; do
+  [[ -n "$key" ]] || continue
+  set_remote_env "$key" "$encoded_value"
+  printf 'Set %s on %s\n' "$key" "$APP_NAME"
+done < <(node - "$APP_ROOT" "$APP_PUBLIC_URL" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+
+const appRoot = process.argv[2];
+const appPublicUrl = String(process.argv[3] || "").trim();
+const envPath = path.join(appRoot, ".env");
+
+const requiredKeys = Object.freeze([
+  "AUTH_PROFILE_MODE",
+  "AUTH_SUPABASE_URL",
+  "AUTH_SUPABASE_PUBLISHABLE_KEY"
+]);
+
+const optionalKeys = Object.freeze([
+  "AI_PROVIDER",
+  "AI_API_KEY",
+  "AI_BASE_URL",
+  "AI_TIMEOUT_MS",
+  "AUTH_OAUTH_PROVIDERS",
+  "AUTH_OAUTH_DEFAULT_PROVIDER",
+  "AUTH_JWT_AUDIENCE"
+]);
+
+function parseDotEnv(source) {
+  const result = new Map();
+
+  for (const rawLine of String(source || "").split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const normalizedLine = line.startsWith("export ") ? line.slice(7).trim() : line;
+    const equalsIndex = normalizedLine.indexOf("=");
+    if (equalsIndex < 1) {
+      continue;
+    }
+
+    const key = normalizedLine.slice(0, equalsIndex).trim();
+    let value = normalizedLine.slice(equalsIndex + 1).trim();
+    if (
+      value.length >= 2 &&
+      ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'")))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    result.set(key, value);
+  }
+
+  return result;
+}
+
+function toBase64(value) {
+  return Buffer.from(String(value || ""), "utf8").toString("base64");
+}
+
+if (!fs.existsSync(envPath)) {
+  console.error("Missing .env in app root.");
+  process.exit(1);
+}
+
+if (!appPublicUrl) {
+  console.error("APP_PUBLIC_URL is required.");
+  process.exit(1);
+}
+
+const envMap = parseDotEnv(fs.readFileSync(envPath, "utf8"));
+const rows = [["APP_PUBLIC_URL", toBase64(appPublicUrl)]];
+
+for (const key of requiredKeys) {
+  const value = String(envMap.get(key) || "").trim();
+  if (!value) {
+    console.error(`Missing required .env value: ${key}`);
+    process.exit(1);
+  }
+  rows.push([key, toBase64(value)]);
+}
+
+for (const key of optionalKeys) {
+  const value = String(envMap.get(key) || "").trim();
+  if (!value) {
+    continue;
+  }
+  rows.push([key, toBase64(value)]);
+}
+
+for (const [key, encodedValue] of rows) {
+  process.stdout.write(`${key}\t${encodedValue}\n`);
+}
+NODE
+)
+
+printf '\nDone.\n'
+printf 'Restart when ready:\n'
+printf '  ssh %q %q\n' "$SSH_TARGET" "dokku ps:restart $APP_NAME"

package/templates/minimal-shell/server/lib/runtimeEnv.js

@@ -0,0 +1,45 @@
+import { createRequire } from "node:module";
+import { surfaceRuntime } from "./surfaceRuntime.js";
+
+const require = createRequire(import.meta.url);
+
+function toPort(value, fallback = 3000) {
+  const parsed = Number.parseInt(String(value || "").trim(), 10);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallback;
+}
+
+let envLoaded = false;
+
+function ensureRuntimeEnvLoaded() {
+  if (envLoaded) {
+    return;
+  }
+  try {
+    const dotenvModule = require("dotenv");
+    const loadDotEnv = dotenvModule?.config;
+    if (typeof loadDotEnv === "function") {
+      loadDotEnv();
+    }
+  } catch {
+    // dotenv is optional in base-shell; bundles can add it when needed.
+  }
+  envLoaded = true;
+}
+
+function resolveRuntimeEnv() {
+  ensureRuntimeEnvLoaded();
+  const serverSurface = surfaceRuntime.normalizeSurfaceMode(
+    process.env.JSKIT_SERVER_SURFACE || process.env.SERVER_SURFACE
+  );
+  return {
+    ...process.env,
+    SERVER_SURFACE: serverSurface,
+    PORT: toPort(process.env.PORT, 3000),
+    HOST: String(process.env.HOST || "").trim() || "0.0.0.0"
+  };
+}
+
+export { resolveRuntimeEnv };

package/templates/minimal-shell/server/lib/surfaceRuntime.js

@@ -0,0 +1,10 @@
+import { createSurfaceRuntime } from "@jskit-ai/kernel/shared/surface/runtime";
+import { config } from "../../config/public.js";
+
+const surfaceRuntime = createSurfaceRuntime({
+  allMode: config.surfaceModeAll,
+  surfaces: config.surfaceDefinitions,
+  defaultSurfaceId: config.surfaceDefaultId
+});
+
+export { surfaceRuntime };

package/templates/minimal-shell/server.js

@@ -0,0 +1,189 @@
+import Fastify from "fastify";
+import fastifyStatic from "@fastify/static";
+import { resolveRuntimeEnv } from "./server/lib/runtimeEnv.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import {
+  registerSurfaceRequestConstraint,
+  resolveRuntimeProfileFromSurface,
+  tryCreateProviderRuntimeFromApp
+} from "@jskit-ai/kernel/server/platform";
+import { matchesPathPrefix, normalizePathname } from "@jskit-ai/kernel/shared/surface/paths";
+import { surfaceRuntime } from "./server/lib/surfaceRuntime.js";
+
+const SPA_INDEX_FILE = "index.html";
+const API_BASE_PATH = "/api";
+const STATIC_GLOBAL_UI_PATHS = Object.freeze([
+  "/assets",
+  "/favicon.svg",
+  "/favicon.ico",
+  "/robots.txt",
+  "/manifest.webmanifest"
+]);
+
+function toRequestPathname(urlValue) {
+  const rawUrl = String(urlValue || "").trim() || "/";
+  try {
+    return normalizePathname(new URL(rawUrl, "http://localhost").pathname || "/");
+  } catch {
+    return normalizePathname(rawUrl.split("?")[0] || "/");
+  }
+}
+
+function isApiPath(pathname) {
+  return matchesPathPrefix(pathname, API_BASE_PATH);
+}
+
+function hasFileExtension(pathname) {
+  return path.extname(normalizePathname(pathname)) !== "";
+}
+
+function resolveGlobalUiPaths(runtimeGlobalUiPaths = []) {
+  const paths = new Set(Array.isArray(runtimeGlobalUiPaths) ? runtimeGlobalUiPaths : []);
+  for (const staticPath of STATIC_GLOBAL_UI_PATHS) {
+    paths.add(staticPath);
+  }
+  return [...paths];
+}
+
+function resolveStaticFilePath(pathname) {
+  const normalizedPathname = normalizePathname(pathname);
+
+  const relativePath = normalizedPathname.replace(/^\/+/, "");
+  if (!relativePath || relativePath.endsWith("/")) {
+    return "";
+  }
+
+  const normalizedRelativePath = path.posix.normalize(relativePath);
+  if (
+    !normalizedRelativePath ||
+    normalizedRelativePath === "." ||
+    normalizedRelativePath === ".." ||
+    normalizedRelativePath.startsWith("../") ||
+    normalizedRelativePath.includes("/../")
+  ) {
+    return "";
+  }
+
+  return normalizedRelativePath;
+}
+
+function canServeStaticFile(distRoot, relativePath) {
+  if (!distRoot || !relativePath) {
+    return false;
+  }
+
+  const normalizedDistRoot = path.resolve(distRoot);
+  const resolvedPath = path.resolve(normalizedDistRoot, relativePath);
+  if (!(resolvedPath === normalizedDistRoot || resolvedPath.startsWith(`${normalizedDistRoot}${path.sep}`))) {
+    return false;
+  }
+
+  return existsSync(resolvedPath);
+}
+
+async function createServer() {
+  const app = Fastify({
+    logger: true,
+    ajv: {
+      customOptions: {
+        allowUnionTypes: true
+      }
+    }
+  });
+
+  app.get("/api/health", async () => {
+    return {
+      ok: true,
+      app: "__APP_NAME__"
+    };
+  });
+  const runtimeEnv = resolveRuntimeEnv();
+  const appRoot = path.resolve(process.cwd());
+  const distRoot = path.resolve(appRoot, "dist");
+  const hasWebBuild = existsSync(path.resolve(distRoot, SPA_INDEX_FILE));
+  const spaDocument = hasWebBuild ? readFileSync(path.resolve(distRoot, SPA_INDEX_FILE), "utf8") : "";
+  const runtime = await tryCreateProviderRuntimeFromApp({
+    appRoot,
+    profile: resolveRuntimeProfileFromSurface({
+      surfaceRuntime,
+      serverSurface: runtimeEnv.SERVER_SURFACE
+    }),
+    env: runtimeEnv,
+    logger: app.log,
+    fastify: app
+  });
+
+  registerSurfaceRequestConstraint({
+    fastify: app,
+    surfaceRuntime,
+    serverSurface: runtimeEnv.SERVER_SURFACE,
+    globalUiPaths: resolveGlobalUiPaths(runtime?.globalUiPaths || [])
+  });
+
+  if (hasWebBuild) {
+    await app.register(fastifyStatic, {
+      root: distRoot,
+      index: false,
+      serve: false
+    });
+  } else {
+    app.log.warn("Frontend build not found (dist/index.html). Page routes will return 404 until `npm run build`.");
+  }
+
+  app.setNotFoundHandler(async (request, reply) => {
+    const pathname = toRequestPathname(request?.url);
+    const method = String(request?.method || "GET")
+      .trim()
+      .toUpperCase();
+    if (isApiPath(pathname) || (method !== "GET" && method !== "HEAD")) {
+      return reply.code(404).send({
+        message: `Route ${method}:${pathname} not found`,
+        error: "Not Found",
+        statusCode: 404
+      });
+    }
+    if (hasFileExtension(pathname)) {
+      const staticFilePath = resolveStaticFilePath(pathname);
+      if (hasWebBuild && staticFilePath && canServeStaticFile(distRoot, staticFilePath)) {
+        return reply.sendFile(staticFilePath);
+      }
+      return reply.code(404).send({
+        message: `Route ${method}:${pathname} not found`,
+        error: "Not Found",
+        statusCode: 404
+      });
+    }
+    if (!hasWebBuild) {
+      return reply.code(404).send({
+        error: "Frontend build is not available. Run `npm run build`."
+      });
+    }
+    return reply.type("text/html; charset=utf-8").send(spaDocument);
+  });
+
+  if (runtime) {
+    app.log.info(
+      {
+        routeCount: runtime.routeCount,
+        surface: surfaceRuntime.normalizeSurfaceMode(runtimeEnv.SERVER_SURFACE),
+        providerPackages: runtime.providerPackageOrder,
+        packageOrder: runtime.packageOrder
+      },
+      "Registered JSKIT provider server runtime."
+    );
+  }
+
+  return app;
+}
+
+async function startServer(options = {}) {
+  const runtimeEnv = resolveRuntimeEnv();
+  const port = Number(options?.port) || runtimeEnv.PORT;
+  const host = String(options?.host || "").trim() || runtimeEnv.HOST;
+  const app = await createServer();
+  await app.listen({ port, host });
+  return app;
+}
+
+export { createServer, startServer };

package/templates/minimal-shell/src/App.vue

@@ -0,0 +1,13 @@
+<template>
+  <v-app>
+    <v-main>
+      <v-container class="py-10 py-md-14">
+        <v-row justify="center">
+          <v-col cols="12" sm="11" md="10" lg="8" xl="7">
+            <RouterView />
+          </v-col>
+        </v-row>
+      </v-container>
+    </v-main>
+  </v-app>
+</template>