@jskit-ai/create-app 0.1.2 → 0.1.6

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

@@ -0,0 +1,33 @@
+const mainClientComponents = [];
+
+function registerMainClientComponent(componentToken, resolveComponent) {
+  const token = String(componentToken || "").trim();
+  if (!token || typeof resolveComponent !== "function") {
+    return;
+  }
+  mainClientComponents.push(
+    Object.freeze({
+      token,
+      resolveComponent
+    })
+  );
+}
+
+class MainClientProvider {
+  static id = "local.main.client";
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function") {
+      throw new Error("MainClientProvider requires application singleton().");
+    }
+
+    for (const entry of mainClientComponents) {
+      app.singleton(entry.token, entry.resolveComponent);
+    }
+  }
+}
+
+export {
+  MainClientProvider,
+  registerMainClientComponent
+};

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

@@ -0,0 +1,9 @@
+/**
+ * Server controller exports.
+ *
+ * Controllers adapt HTTP requests to service calls.
+ *
+ * Example:
+ * export { MainHelloController } from "./MainHelloController.js";
+ */
+export {};

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

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

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

@@ -0,0 +1,22 @@
+import { loadAppConfig } from "../support/loadAppConfig.js";
+
+class MainServiceProvider {
+  static id = "local.main";
+
+  // Optional: register container bindings here (services/singletons).
+  async register(app) {
+    const appConfig = await loadAppConfig({
+      moduleUrl: import.meta.url
+    });
+    app.instance("appConfig", appConfig);
+  }
+
+  // Start backend features here:
+  // 1) define shared validators/resources in `src/shared/schemas`
+  // 2) resolve router with `app.make(KERNEL_TOKENS.HttpRouter)`
+  // 3) register routes and handlers
+  // 4) extract to services/controllers/routes as the feature grows
+  boot() {}
+}
+
+export { MainServiceProvider };

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

@@ -0,0 +1,9 @@
+/**
+ * Server route definition exports.
+ *
+ * Route builders define HTTP method/path/schema/handler wiring.
+ *
+ * Example:
+ * export { buildMainRoutes } from "./mainRoutes.js";
+ */
+export {};

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

@@ -0,0 +1,9 @@
+/**
+ * Server service exports.
+ *
+ * Services hold domain logic and are called by controllers.
+ *
+ * Example:
+ * export { MainHelloService } from "./MainHelloService.js";
+ */
+export {};

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

@@ -0,0 +1,55 @@
+import { access, constants as fsConstants } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+async function fileExists(absolutePath) {
+  try {
+    await access(absolutePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveAppRootFrom(moduleDirectory) {
+  let currentDirectory = path.resolve(moduleDirectory);
+
+  while (true) {
+    const candidateConfigPath = path.join(currentDirectory, "config", "public.js");
+    if (await fileExists(candidateConfigPath)) {
+      return currentDirectory;
+    }
+
+    const parentDirectory = path.dirname(currentDirectory);
+    if (parentDirectory === currentDirectory) {
+      throw new Error("Unable to locate app root (missing config/public.js).");
+    }
+    currentDirectory = parentDirectory;
+  }
+}
+
+async function loadConfigModule(absolutePath) {
+  if (!(await fileExists(absolutePath))) {
+    return {};
+  }
+
+  const loadedModule = await import(pathToFileURL(absolutePath).href);
+  const loadedConfig = loadedModule?.config;
+  return loadedConfig && typeof loadedConfig === "object" && !Array.isArray(loadedConfig) ? loadedConfig : {};
+}
+
+async function loadAppConfig({ moduleUrl = import.meta.url } = {}) {
+  const moduleDirectory = path.dirname(fileURLToPath(moduleUrl));
+  const appRoot = await resolveAppRootFrom(moduleDirectory);
+  const [publicConfig, serverConfig] = await Promise.all([
+    loadConfigModule(path.join(appRoot, "config", "public.js")),
+    loadConfigModule(path.join(appRoot, "config", "server.js"))
+  ]);
+
+  return Object.freeze({
+    ...publicConfig,
+    ...serverConfig
+  });
+}
+
+export { loadAppConfig };

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

@@ -0,0 +1,8 @@
+/**
+ * Shared entrypoint for code used by both client and server.
+ *
+ * Example:
+ * export * from "./schemas/index.js";
+ * export * from "./constants/index.js";
+ */
+export {};

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

@@ -0,0 +1,20 @@
+/**
+ * Shared transport validators/resources live here.
+ *
+ * Example:
+ * import { Type } from "@fastify/type-provider-typebox";
+ *
+ * export const helloSchema = {
+ *   query: Type.Object(
+ *     { name: Type.Optional(Type.String({ minLength: 1, maxLength: 80 })) },
+ *     { additionalProperties: false }
+ *   ),
+ *   response: {
+ *     200: Type.Object(
+ *       { ok: Type.Boolean(), message: Type.String({ minLength: 1 }) },
+ *       { additionalProperties: false }
+ *     )
+ *   }
+ * };
+ */
+export {};

package/templates/base-shell/scripts/dev-bootstrap-jskit.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+APP_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BOOTSTRAP_MODE_RAW="${JSKIT_DEV_BOOTSTRAP:-auto}"
+BOOTSTRAP_MODE="$(echo "$BOOTSTRAP_MODE_RAW" | tr '[:upper:]' '[:lower:]')"
+
+is_valid_jskit_repo_root() {
+  local candidate_root="$1"
+  [[ -d "$candidate_root/packages" && -d "$candidate_root/packages/kernel" && -d "$candidate_root/tooling" ]]
+}
+
+find_jskit_repo_root() {
+  local current_dir="$1"
+  while true; do
+    if is_valid_jskit_repo_root "$current_dir"; then
+      echo "$current_dir"
+      return 0
+    fi
+    if [[ "$current_dir" == "/" ]]; then
+      return 1
+    fi
+    current_dir="$(dirname "$current_dir")"
+  done
+}
+
+resolve_local_repo_root() {
+  if [[ -n "${JSKIT_REPO_ROOT:-}" ]]; then
+    echo "$JSKIT_REPO_ROOT"
+    return 0
+  fi
+
+  find_jskit_repo_root "$APP_ROOT" || true
+}
+
+is_dokku_environment() {
+  [[ -n "${DOKKU_APP_NAME:-}" || -n "${DOKKU_APP_TYPE:-}" ]]
+}
+
+resolve_bootstrap_mode() {
+  local normalized_mode="$1"
+  if [[ "$normalized_mode" != "auto" ]]; then
+    echo "$normalized_mode"
+    return 0
+  fi
+
+  if is_dokku_environment; then
+    echo "on"
+    return 0
+  fi
+
+  echo "off"
+}
+
+BOOTSTRAP_MODE="$(resolve_bootstrap_mode "$BOOTSTRAP_MODE")"
+LOCAL_REPO_ROOT="$(resolve_local_repo_root)"
+
+if [[ "$BOOTSTRAP_MODE" == "0" || "$BOOTSTRAP_MODE" == "false" || "$BOOTSTRAP_MODE" == "off" ]]; then
+  echo "[dev-bootstrap] skipped (JSKIT_DEV_BOOTSTRAP disabled)."
+  exit 0
+fi
+
+if is_valid_jskit_repo_root "$LOCAL_REPO_ROOT"; then
+  echo "[dev-bootstrap] using local JSKIT repo: $LOCAL_REPO_ROOT"
+  JSKIT_REPO_ROOT="$LOCAL_REPO_ROOT" bash "$APP_ROOT/scripts/verdaccio-reset-and-publish-packages.sh"
+  exit 0
+fi
+
+if [[ "$BOOTSTRAP_MODE" != "1" && "$BOOTSTRAP_MODE" != "true" && "$BOOTSTRAP_MODE" != "on" ]]; then
+  echo "[dev-bootstrap] skipped (no local JSKIT repo at $LOCAL_REPO_ROOT)."
+  echo "[dev-bootstrap] set JSKIT_DEV_BOOTSTRAP=1 and JSKIT_GITHUB_TARBALL_URL to force remote bootstrap."
+  exit 0
+fi
+
+JSKIT_GITHUB_TARBALL_URL="${JSKIT_GITHUB_TARBALL_URL:-}"
+if [[ -z "$JSKIT_GITHUB_TARBALL_URL" ]]; then
+  echo "[dev-bootstrap] failed: local JSKIT repo not found at $LOCAL_REPO_ROOT and JSKIT_GITHUB_TARBALL_URL is not set." >&2
+  echo "[dev-bootstrap] set JSKIT_REPO_ROOT to a local checkout or set JSKIT_GITHUB_TARBALL_URL to an accessible tarball URL." >&2
+  exit 1
+fi
+
+TMP_DIR="$(mktemp -d)"
+TARBALL_PATH="$TMP_DIR/jskit-ai.tar.gz"
+EXTRACT_DIR="$TMP_DIR/extracted"
+
+cleanup() {
+  rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT
+
+echo "[dev-bootstrap] downloading $JSKIT_GITHUB_TARBALL_URL"
+curl -fsSL "$JSKIT_GITHUB_TARBALL_URL" -o "$TARBALL_PATH"
+
+mkdir -p "$EXTRACT_DIR"
+tar -xzf "$TARBALL_PATH" -C "$EXTRACT_DIR"
+
+JSKIT_REPO_ROOT="$(find "$EXTRACT_DIR" -mindepth 1 -maxdepth 1 -type d | head -n 1 || true)"
+if [[ -z "${JSKIT_REPO_ROOT:-}" ]]; then
+  echo "[dev-bootstrap] failed: extracted archive is empty." >&2
+  exit 1
+fi
+
+if [[ ! -d "$JSKIT_REPO_ROOT/packages" || ! -d "$JSKIT_REPO_ROOT/packages/kernel" || ! -d "$JSKIT_REPO_ROOT/tooling" ]]; then
+  echo "[dev-bootstrap] failed: extracted archive does not look like jskit-ai monorepo." >&2
+  echo "[dev-bootstrap] extracted root: $JSKIT_REPO_ROOT" >&2
+  exit 1
+fi
+
+echo "[dev-bootstrap] publishing packages from extracted repo: $JSKIT_REPO_ROOT"
+JSKIT_REPO_ROOT="$JSKIT_REPO_ROOT" bash "$APP_ROOT/scripts/verdaccio-reset-and-publish-packages.sh"

package/templates/base-shell/scripts/just_run_verde

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Starts a local Verdaccio registry for JSKIT package publish/install testing.
+# - Default: runs in background (nohup) and prints PID/log file locations.
+# - --fg: runs Verdaccio in foreground for interactive debugging.
+#
+# Env overrides:
+# - VERDACCIO_LISTEN (default: 127.0.0.1:4873)
+# - VERDACCIO_CONFIG (default: ./scripts/verdaccio/config.yaml, fallback ~/.config/verdaccio/config.yaml)
+# - VERDACCIO_LOG_FILE (default: /tmp/verdaccio.log)
+# - VERDACCIO_PID_FILE (default: /tmp/verdaccio.pid)
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VERDACCIO_LISTEN="${VERDACCIO_LISTEN:-127.0.0.1:4873}"
+DEFAULT_VERDACCIO_CONFIG="$ROOT_DIR/scripts/verdaccio/config.yaml"
+if [[ -f "$DEFAULT_VERDACCIO_CONFIG" ]]; then
+  VERDACCIO_CONFIG="${VERDACCIO_CONFIG:-$DEFAULT_VERDACCIO_CONFIG}"
+else
+  VERDACCIO_CONFIG="${VERDACCIO_CONFIG:-$HOME/.config/verdaccio/config.yaml}"
+fi
+VERDACCIO_LOG_FILE="${VERDACCIO_LOG_FILE:-/tmp/verdaccio.log}"
+VERDACCIO_PID_FILE="${VERDACCIO_PID_FILE:-/tmp/verdaccio.pid}"
+CONFIG_DIR="$(cd "$(dirname "$VERDACCIO_CONFIG")" && pwd)"
+
+if [[ "${1:-}" == "--fg" ]]; then
+  cd "$CONFIG_DIR"
+  exec npx verdaccio --listen "$VERDACCIO_LISTEN" --config "$VERDACCIO_CONFIG"
+fi
+
+(
+  cd "$CONFIG_DIR"
+  nohup npx verdaccio --listen "$VERDACCIO_LISTEN" --config "$VERDACCIO_CONFIG" >"$VERDACCIO_LOG_FILE" 2>&1 &
+  echo "$!" >"$VERDACCIO_PID_FILE"
+)
+echo "Verdaccio started in background."
+echo "PID file: $VERDACCIO_PID_FILE"
+echo "Log file: $VERDACCIO_LOG_FILE"

package/templates/base-shell/scripts/link-local-jskit-packages.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Re-link installed @jskit-ai packages in node_modules to a local jskit-ai monorepo checkout.
+# Run this AFTER `npm install` when you want live local development without publishing packages.
+#
+# Usage:
+#   npm run link:local:jskit
+#   JSKIT_REPO_ROOT=/abs/path/to/jskit-ai npm run link:local:jskit
+set -euo pipefail
+
+APP_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCOPE_DIR="$APP_ROOT/node_modules/@jskit-ai"
+
+is_valid_jskit_repo_root() {
+  local candidate_root="$1"
+  [[ -d "$candidate_root/packages" && -d "$candidate_root/packages/kernel" && -d "$candidate_root/tooling" ]]
+}
+
+resolve_local_repo_root() {
+  if [[ -n "${JSKIT_REPO_ROOT:-}" ]]; then
+    echo "$JSKIT_REPO_ROOT"
+    return 0
+  fi
+
+  local current_dir="$APP_ROOT"
+  while true; do
+    if is_valid_jskit_repo_root "$current_dir"; then
+      echo "$current_dir"
+      return 0
+    fi
+    if [[ "$current_dir" == "/" ]]; then
+      return 1
+    fi
+    current_dir="$(dirname "$current_dir")"
+  done
+}
+
+JSKIT_REPO_ROOT="$(resolve_local_repo_root || true)"
+
+if [[ ! -d "$SCOPE_DIR" ]]; then
+  echo "[link-local] @jskit-ai scope not found at $SCOPE_DIR (run npm install first)." >&2
+  exit 1
+fi
+
+if [[ -z "$JSKIT_REPO_ROOT" ]]; then
+  echo "[link-local] no JSKIT repository found." >&2
+  echo "[link-local] set JSKIT_REPO_ROOT to a local jskit-ai checkout path." >&2
+  exit 1
+fi
+
+if ! is_valid_jskit_repo_root "$JSKIT_REPO_ROOT"; then
+  echo "[link-local] JSKIT_REPO_ROOT is not a valid jskit-ai checkout: $JSKIT_REPO_ROOT" >&2
+  exit 1
+fi
+
+resolve_source_dir() {
+  local package_dir_name="$1"
+  case "$package_dir_name" in
+    config-eslint|create-app|jskit-cli|jskit-catalog)
+      echo "$JSKIT_REPO_ROOT/tooling/$package_dir_name"
+      ;;
+    *)
+      echo "$JSKIT_REPO_ROOT/packages/$package_dir_name"
+      ;;
+  esac
+}
+
+linked_count=0
+skipped_count=0
+
+for installed_path in "$SCOPE_DIR"/*; do
+  if [[ ! -e "$installed_path" && ! -L "$installed_path" ]]; then
+    continue
+  fi
+
+  package_dir_name="$(basename "$installed_path")"
+  source_dir="$(resolve_source_dir "$package_dir_name")"
+
+  if [[ ! -f "$source_dir/package.json" ]]; then
+    echo "[link-local] skip @jskit-ai/$package_dir_name (no local source at $source_dir)"
+    skipped_count=$((skipped_count + 1))
+    continue
+  fi
+
+  rm -rf "$installed_path"
+  ln -s "$source_dir" "$installed_path"
+  echo "[link-local] linked @jskit-ai/$package_dir_name -> $source_dir"
+  linked_count=$((linked_count + 1))
+done
+
+echo "[link-local] done. linked=$linked_count skipped=$skipped_count"

package/templates/base-shell/scripts/update-jskit-packages.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+APP_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PACKAGE_JSON_PATH="$APP_ROOT/package.json"
+JSKIT_REGISTRY="${JSKIT_REGISTRY:-}"
+
+if [[ ! -f "$PACKAGE_JSON_PATH" ]]; then
+  echo "[jskit:update] package.json not found: $PACKAGE_JSON_PATH" >&2
+  exit 1
+fi
+
+readarray -t runtime_packages < <(
+  node -e '
+    const fs = require("node:fs");
+    const packageJson = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+    const dependencies = packageJson?.dependencies || {};
+    const names = Object.keys(dependencies).filter((name) => name.startsWith("@jskit-ai/")).sort();
+    for (const name of names) {
+      process.stdout.write(`${name}\n`);
+    }
+  ' "$PACKAGE_JSON_PATH"
+)
+
+readarray -t dev_packages < <(
+  node -e '
+    const fs = require("node:fs");
+    const packageJson = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+    const dependencies = packageJson?.devDependencies || {};
+    const names = Object.keys(dependencies).filter((name) => name.startsWith("@jskit-ai/")).sort();
+    for (const name of names) {
+      process.stdout.write(`${name}\n`);
+    }
+  ' "$PACKAGE_JSON_PATH"
+)
+
+runtime_specs=()
+for package_name in "${runtime_packages[@]}"; do
+  runtime_specs+=("${package_name}@latest")
+done
+
+dev_specs=()
+for package_name in "${dev_packages[@]}"; do
+  dev_specs+=("${package_name}@latest")
+done
+
+registry_args=()
+if [[ -n "$JSKIT_REGISTRY" ]]; then
+  registry_args+=(--registry "$JSKIT_REGISTRY")
+fi
+
+if (( ${#runtime_specs[@]} == 0 && ${#dev_specs[@]} == 0 )); then
+  echo "[jskit:update] no @jskit-ai packages found in dependencies."
+  exit 0
+fi
+
+if (( ${#runtime_specs[@]} > 0 )); then
+  echo "[jskit:update] updating runtime packages: ${runtime_specs[*]}"
+  (
+    cd "$APP_ROOT"
+    npm install --save-exact "${registry_args[@]}" "${runtime_specs[@]}"
+  )
+fi
+
+if (( ${#dev_specs[@]} > 0 )); then
+  echo "[jskit:update] updating dev packages: ${dev_specs[*]}"
+  (
+    cd "$APP_ROOT"
+    npm install --save-dev --save-exact "${registry_args[@]}" "${dev_specs[@]}"
+  )
+fi
+
+echo "[jskit:update] done."

package/templates/base-shell/scripts/verdaccio/config.yaml

@@ -0,0 +1,26 @@
+storage: ./storage
+
+auth:
+  htpasswd:
+    file: ./htpasswd
+
+uplinks:
+  npmjs:
+    url: https://registry.npmjs.org/
+
+packages:
+  "@jskit-ai/*":
+    access: $all
+    publish: $all
+    unpublish: $all
+
+  "**":
+    access: $all
+    publish: $all
+    unpublish: $all
+    proxy: npmjs
+
+log:
+  - type: stdout
+    format: pretty
+    level: http