@jskit-ai/create-app 0.1.0

package/README.md

@@ -0,0 +1,22 @@
+# @jskit-ai/create-app
+
+Scaffold a minimal JSKIT app shell from in-repo templates.
+
+## Usage
+
+```bash
+jskit-create-app my-app
+```
+
+```bash
+jskit-create-app --interactive
+```
+
+## Options
+
+- `--template <name>` template name under `templates/` (default `base-shell`)
+- `--title <text>` override the generated app title placeholder
+- `--target <path>` output directory (default `./<app-name>`)
+- `--force` allow writes into non-empty target directories
+- `--dry-run` preview writes only
+- `--interactive` prompt for app values

package/bin/jskit-create-app.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { runCli } from "../src/index.js";
+
+const exitCode = await runCli(process.argv.slice(2));
+if (exitCode !== 0) {
+  process.exit(exitCode);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@jskit-ai/create-app",
+  "version": "0.1.0",
+  "description": "Scaffold minimal JSKIT app shells.",
+  "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "bin": {
+    "jskit-create-app": "bin/jskit-create-app.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": "20.x"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mobily-enterprises/jskit-ai.git",
+    "directory": "packages/tooling/create-app"
+  },
+  "bugs": {
+    "url": "https://github.com/mobily-enterprises/jskit-ai/issues"
+  },
+  "homepage": "https://github.com/mobily-enterprises/jskit-ai/tree/main/packages/tooling/create-app#readme",
+  "keywords": [
+    "jskit",
+    "scaffold",
+    "cli",
+    "starter"
+  ]
+}

package/src/index.js

@@ -0,0 +1,498 @@
+import { chmod, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_TEMPLATE = "base-shell";
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const TEMPLATES_ROOT = path.join(PACKAGE_ROOT, "templates");
+
+function createCliError(message, { showUsage = false, exitCode = 1 } = {}) {
+  const error = new Error(String(message || "Command failed."));
+  error.showUsage = Boolean(showUsage);
+  error.exitCode = Number.isInteger(exitCode) ? exitCode : 1;
+  return error;
+}
+
+function shellQuote(value) {
+  const raw = String(value ?? "");
+  if (!raw) {
+    return "''";
+  }
+  if (/^[A-Za-z0-9_./:=+,-]+$/.test(raw)) {
+    return raw;
+  }
+  return `'${raw.replace(/'/g, "'\\''")}'`;
+}
+
+function toAppTitle(appName) {
+  const words = String(appName)
+    .trim()
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`);
+
+  return words.length > 0 ? words.join(" ") : "App";
+}
+
+function validateAppName(appName, { showUsage = true } = {}) {
+  if (!appName || typeof appName !== "string") {
+    throw createCliError("Missing app name.", { showUsage });
+  }
+
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(appName)) {
+    throw createCliError(
+      `Invalid app name "${appName}". Use lowercase letters, numbers, and dashes only.`,
+      { showUsage }
+    );
+  }
+}
+
+function parseOptionWithValue(argv, index, optionName) {
+  const nextValue = argv[index + 1];
+  if (!nextValue || nextValue.startsWith("-")) {
+    throw createCliError(`Option ${optionName} requires a value.`, {
+      showUsage: true
+    });
+  }
+  return {
+    value: nextValue,
+    nextIndex: index + 1
+  };
+}
+
+function parseCliArgs(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  const options = {
+    appName: null,
+    appTitle: null,
+    template: DEFAULT_TEMPLATE,
+    target: null,
+    force: false,
+    dryRun: false,
+    help: false,
+    interactive: false
+  };
+
+  const positionalArgs = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index] || "");
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === "--force") {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg === "--interactive") {
+      options.interactive = true;
+      continue;
+    }
+
+    if (arg === "--template") {
+      const { value, nextIndex } = parseOptionWithValue(args, index, "--template");
+      options.template = value;
+      index = nextIndex;
+      continue;
+    }
+
+    if (arg.startsWith("--template=")) {
+      options.template = arg.slice("--template=".length);
+      continue;
+    }
+
+    if (arg === "--target") {
+      const { value, nextIndex } = parseOptionWithValue(args, index, "--target");
+      options.target = value;
+      index = nextIndex;
+      continue;
+    }
+
+    if (arg.startsWith("--target=")) {
+      options.target = arg.slice("--target=".length);
+      continue;
+    }
+
+    if (arg === "--title") {
+      const { value, nextIndex } = parseOptionWithValue(args, index, "--title");
+      options.appTitle = value;
+      index = nextIndex;
+      continue;
+    }
+
+    if (arg.startsWith("--title=")) {
+      options.appTitle = arg.slice("--title=".length);
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw createCliError(`Unknown option: ${arg}`, {
+        showUsage: true
+      });
+    }
+
+    positionalArgs.push(arg);
+  }
+
+  if (positionalArgs.length > 1) {
+    throw createCliError("Only one <app-name> argument is allowed.", {
+      showUsage: true
+    });
+  }
+
+  if (positionalArgs.length === 1) {
+    options.appName = positionalArgs[0];
+  }
+
+  if (!options.help && !options.interactive && positionalArgs.length !== 1) {
+    throw createCliError("Expected exactly one <app-name> argument.", {
+      showUsage: true
+    });
+  }
+
+  return options;
+}
+
+function printUsage(stream = process.stderr) {
+  stream.write("Usage: jskit-create-app [app-name] [options]\n");
+  stream.write("\n");
+  stream.write("Options:\n");
+  stream.write(`  --template <name>  Template folder under templates/ (default: ${DEFAULT_TEMPLATE})\n`);
+  stream.write("  --title <text>     App title used for template replacements\n");
+  stream.write("  --target <path>    Target directory (default: ./<app-name>)\n");
+  stream.write("  --force            Allow writing into a non-empty target directory\n");
+  stream.write("  --dry-run          Print planned writes without changing the filesystem\n");
+  stream.write("  --interactive      Prompt for app values instead of passing all flags\n");
+  stream.write("  -h, --help         Show this help\n");
+}
+
+function applyPlaceholders(source, replacements) {
+  let output = String(source || "");
+  for (const [placeholder, value] of Object.entries(replacements)) {
+    output = output.split(placeholder).join(String(value));
+  }
+  return output;
+}
+
+async function resolveTemplateDirectory(templateName) {
+  const cleanTemplate = String(templateName || "").trim();
+  if (!cleanTemplate) {
+    throw createCliError("Template name cannot be empty.", {
+      showUsage: true
+    });
+  }
+
+  const templateDir = path.join(TEMPLATES_ROOT, cleanTemplate);
+
+  try {
+    const templateStats = await stat(templateDir);
+    if (!templateStats.isDirectory()) {
+      throw createCliError(`Template "${cleanTemplate}" is not a directory.`);
+    }
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw createCliError(`Unknown template "${cleanTemplate}".`);
+    }
+    throw error;
+  }
+
+  return templateDir;
+}
+
+async function ensureTargetDirectoryState(targetDirectory, { force = false, dryRun = false } = {}) {
+  let targetExists = false;
+
+  try {
+    const targetStats = await stat(targetDirectory);
+    targetExists = true;
+    if (!targetStats.isDirectory()) {
+      throw createCliError(`Target path exists and is not a directory: ${targetDirectory}`);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  if (!targetExists) {
+    if (!dryRun) {
+      await mkdir(targetDirectory, { recursive: true });
+    }
+    return;
+  }
+
+  const entries = await readdir(targetDirectory);
+  if (entries.length > 0 && !force) {
+    throw createCliError(
+      `Target directory is not empty: ${targetDirectory}. Use --force to allow writing into it.`
+    );
+  }
+}
+
+function sortEntriesByName(entries) {
+  return [...entries].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function mapTemplatePathToTargetPath(relativePath) {
+  const pathSegments = String(relativePath || "")
+    .split(path.sep)
+    .map((segment) => (segment === "gitignore" ? ".gitignore" : segment));
+  return pathSegments.join(path.sep);
+}
+
+async function writeTemplateFile(sourcePath, targetPath, replacements) {
+  const sourceBody = await readFile(sourcePath, "utf8");
+  const targetBody = applyPlaceholders(sourceBody, replacements);
+
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, targetBody, "utf8");
+
+  const sourceStats = await stat(sourcePath);
+  await chmod(targetPath, sourceStats.mode & 0o777);
+}
+
+async function copyTemplateDirectory({ templateDirectory, targetDirectory, replacements, dryRun }) {
+  const touchedFiles = [];
+
+  async function traverse(relativePath = "") {
+    const sourceDirectory = path.join(templateDirectory, relativePath);
+    const sourceEntries = sortEntriesByName(await readdir(sourceDirectory, { withFileTypes: true }));
+
+    for (const entry of sourceEntries) {
+      const entryRelativePath = relativePath ? path.join(relativePath, entry.name) : entry.name;
+      const targetRelativePath = mapTemplatePathToTargetPath(entryRelativePath);
+      const sourcePath = path.join(templateDirectory, entryRelativePath);
+      const targetPath = path.join(targetDirectory, targetRelativePath);
+
+      if (entry.isDirectory()) {
+        if (!dryRun) {
+          await mkdir(targetPath, { recursive: true });
+        }
+        await traverse(entryRelativePath);
+        continue;
+      }
+
+      if (entry.isFile()) {
+        touchedFiles.push(targetRelativePath);
+        if (!dryRun) {
+          await writeTemplateFile(sourcePath, targetPath, replacements);
+        }
+        continue;
+      }
+
+      throw createCliError(`Unsupported template entry type at ${entryRelativePath}.`);
+    }
+  }
+
+  await traverse();
+  return touchedFiles;
+}
+
+function toRelativeTargetLabel(cwd, targetDirectory) {
+  const relativePath = path.relative(cwd, targetDirectory);
+  if (!relativePath || relativePath === ".") {
+    return ".";
+  }
+  if (relativePath.startsWith("..")) {
+    return targetDirectory;
+  }
+  return `./${relativePath}`;
+}
+
+async function askQuestion(readline, label, defaultValue) {
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  const response = await readline.question(`${label}${suffix}: `);
+  const trimmed = response.trim();
+  return trimmed || defaultValue;
+}
+
+async function askYesNoQuestion(readline, label, defaultValue) {
+  const prompt = defaultValue ? "Y/n" : "y/N";
+
+  while (true) {
+    const response = await readline.question(`${label} [${prompt}]: `);
+    const normalized = response.trim().toLowerCase();
+    if (!normalized) {
+      return defaultValue;
+    }
+    if (normalized === "y" || normalized === "yes") {
+      return true;
+    }
+    if (normalized === "n" || normalized === "no") {
+      return false;
+    }
+  }
+}
+
+async function collectInteractiveOptions({ parsed, stdout = process.stdout, stderr = process.stderr, stdin = process.stdin }) {
+  const readline = createInterface({
+    input: stdin,
+    output: stdout
+  });
+
+  try {
+    let appName = String(parsed.appName || "").trim();
+    while (true) {
+      appName = await askQuestion(readline, "App name", appName);
+      try {
+        validateAppName(appName, { showUsage: false });
+        break;
+      } catch (error) {
+        stderr.write(`Error: ${error?.message || String(error)}\n`);
+      }
+    }
+
+    const defaultTitle = String(parsed.appTitle || "").trim() || toAppTitle(appName);
+    const appTitle = await askQuestion(readline, "App title", defaultTitle);
+
+    const defaultTarget = String(parsed.target || "").trim() || appName;
+    const target = await askQuestion(readline, "Target directory", defaultTarget);
+
+    const defaultTemplate = String(parsed.template || "").trim() || DEFAULT_TEMPLATE;
+    const template = await askQuestion(readline, "Template", defaultTemplate);
+
+    const force = await askYesNoQuestion(
+      readline,
+      "Allow writing into non-empty target directories",
+      Boolean(parsed.force)
+    );
+
+    return {
+      appName,
+      appTitle,
+      target,
+      template,
+      force
+    };
+  } finally {
+    readline.close();
+  }
+}
+
+export async function createApp({
+  appName,
+  appTitle = null,
+  template = DEFAULT_TEMPLATE,
+  target = null,
+  force = false,
+  dryRun = false,
+  cwd = process.cwd()
+}) {
+  const resolvedAppName = String(appName || "").trim();
+  validateAppName(resolvedAppName);
+
+  const resolvedAppTitle = String(appTitle || "").trim() || toAppTitle(resolvedAppName);
+
+  const resolvedCwd = path.resolve(cwd);
+  const targetDirectory = path.resolve(resolvedCwd, target ? String(target) : resolvedAppName);
+  const templateDirectory = await resolveTemplateDirectory(template);
+
+  await ensureTargetDirectoryState(targetDirectory, {
+    force,
+    dryRun
+  });
+
+  const replacements = {
+    __APP_NAME__: resolvedAppName,
+    __APP_TITLE__: resolvedAppTitle
+  };
+
+  const touchedFiles = await copyTemplateDirectory({
+    templateDirectory,
+    targetDirectory,
+    replacements,
+    dryRun
+  });
+
+  return {
+    appName: resolvedAppName,
+    appTitle: resolvedAppTitle,
+    template: String(template),
+    targetDirectory,
+    dryRun,
+    touchedFiles
+  };
+}
+
+export async function runCli(
+  argv,
+  {
+    stdout = process.stdout,
+    stderr = process.stderr,
+    stdin = process.stdin,
+    cwd = process.cwd()
+  } = {}
+) {
+  try {
+    const parsed = parseCliArgs(argv);
+
+    if (parsed.help) {
+      printUsage(stdout);
+      return 0;
+    }
+
+    const resolvedOptions = parsed.interactive
+      ? {
+          ...parsed,
+          ...(await collectInteractiveOptions({
+            parsed,
+            stdout,
+            stderr,
+            stdin
+          }))
+        }
+      : parsed;
+
+    const result = await createApp({
+      appName: resolvedOptions.appName,
+      appTitle: resolvedOptions.appTitle,
+      template: resolvedOptions.template,
+      target: resolvedOptions.target,
+      force: resolvedOptions.force,
+      dryRun: resolvedOptions.dryRun,
+      cwd
+    });
+
+    const targetLabel = toRelativeTargetLabel(path.resolve(cwd), result.targetDirectory);
+    if (result.dryRun) {
+      stdout.write(
+        `[dry-run] Would create app "${result.appName}" from template "${result.template}" at ${targetLabel}.\n`
+      );
+    } else {
+      stdout.write(`Created app "${result.appName}" from template "${result.template}" at ${targetLabel}.\n`);
+    }
+
+    stdout.write(`${result.dryRun ? "Planned" : "Written"} files (${result.touchedFiles.length}):\n`);
+    for (const filePath of result.touchedFiles) {
+      stdout.write(`- ${filePath}\n`);
+    }
+
+    if (!result.dryRun) {
+      stdout.write("\n");
+      stdout.write("Next steps:\n");
+      stdout.write(`- cd ${shellQuote(targetLabel)}\n`);
+      stdout.write("- npm install\n");
+      stdout.write("- npm run dev\n");
+    }
+
+    return 0;
+  } catch (error) {
+    stderr.write(`Error: ${error?.message || String(error)}\n`);
+    if (error?.showUsage) {
+      stderr.write("\n");
+      printUsage(stderr);
+    }
+    return Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+  }
+}

package/templates/base-shell/README.md

@@ -0,0 +1,33 @@
+# __APP_TITLE__
+
+Minimal JSKIT starter shell.
+
+## What This Is
+
+This is the smallest practical JSKIT app host:
+
+- tiny Fastify server (`/api/v1/health`)
+- tiny Vue client shell
+- standardized scripts via `@jskit-ai/app-scripts`
+- framework composition seed file: `framework/app.manifest.mjs`
+
+## What This Is Not
+
+This app intentionally does not include:
+
+- db wiring
+- auth/workspace modules
+- billing/chat/social/ai modules
+- app-local framework composition engines
+
+Those are layered in later as framework packs/modules.
+
+## Run
+
+```bash
+npm install
+npm run dev
+npm run server
+npm run test
+npm run test:client
+```

package/templates/base-shell/app.scripts.config.mjs

@@ -0,0 +1,3 @@
+import { createNodeVueFastifyScriptsConfig } from "@jskit-ai/app-scripts";
+
+export default createNodeVueFastifyScriptsConfig();

package/templates/base-shell/bin/server.js

@@ -0,0 +1,8 @@
+import { startServer } from "../server.js";
+
+try {
+  await startServer();
+} catch (error) {
+  console.error("Failed to start __APP_NAME__ server:", error);
+  process.exitCode = 1;
+}

package/templates/base-shell/eslint.config.mjs

@@ -0,0 +1,10 @@
+import { baseConfig, nodeConfig, webConfig } from "@jskit-ai/config-eslint";
+
+export default [
+  {
+    ignores: ["dist/**", "node_modules/**", "coverage/**"]
+  },
+  ...baseConfig,
+  ...webConfig,
+  ...nodeConfig
+];

package/templates/base-shell/favicon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="12" fill="#111827" />
+  <path
+    d="M20 16h24v8H28v20c0 6-4 10-10 10h-2v-8h2c2 0 2-1 2-3V16z"
+    fill="#22d3ee"
+  />
+</svg>

package/templates/base-shell/framework/app.manifest.mjs

@@ -0,0 +1,8 @@
+export default Object.freeze({
+  manifestVersion: 1,
+  appId: "__APP_NAME__",
+  profileId: "web-saas-default",
+  mode: "strict",
+  enforceProfileRequired: true,
+  optionalModulePacks: ["core"]
+});

package/templates/base-shell/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+coverage/
+test-results/
+.env
+.env.*
+!.env.example

package/templates/base-shell/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>__APP_TITLE__</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/%VITE_CLIENT_ENTRY%"></script>
+  </body>
+</html>

package/templates/base-shell/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Minimal JSKIT base app (Fastify + Vue)",
+  "engines": {
+    "node": "20.x"
+  },
+  "scripts": {
+    "server": "jskit-app-scripts server",
+    "start": "jskit-app-scripts start",
+    "dev": "jskit-app-scripts dev",
+    "build": "jskit-app-scripts build",
+    "preview": "jskit-app-scripts preview",
+    "lint": "jskit-app-scripts lint",
+    "lint:process-env": "jskit-app-scripts lint:process-env",
+    "test": "jskit-app-scripts test",
+    "test:client": "jskit-app-scripts test:client"
+  },
+  "dependencies": {
+    "@jskit-ai/app-scripts": "0.1.0",
+    "fastify": "^5.7.4",
+    "vue": "^3.5.13"
+  },
+  "devDependencies": {
+    "@jskit-ai/config-eslint": "0.1.0",
+    "@vitejs/plugin-vue": "^5.2.1",
+    "eslint": "^9.39.1",
+    "vite": "^6.1.0",
+    "vitest": "^4.0.18"
+  }
+}

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

@@ -0,0 +1,16 @@
+function toPort(value, fallback = 3000) {
+  const parsed = Number.parseInt(String(value || "").trim(), 10);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallback;
+}
+
+function resolveRuntimeEnv() {
+  return {
+    PORT: toPort(process.env.PORT, 3000),
+    HOST: String(process.env.HOST || "").trim() || "0.0.0.0"
+  };
+}
+
+export { resolveRuntimeEnv };

package/templates/base-shell/server.js

@@ -0,0 +1,26 @@
+import Fastify from "fastify";
+import { resolveRuntimeEnv } from "./server/lib/runtimeEnv.js";
+
+function createServer() {
+  const app = Fastify({ logger: true });
+
+  app.get("/api/v1/health", async () => {
+    return {
+      ok: true,
+      app: "__APP_NAME__"
+    };
+  });
+
+  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 = createServer();
+  await app.listen({ port, host });
+  return app;
+}
+
+export { createServer, startServer };

package/templates/base-shell/src/main.js

@@ -0,0 +1,30 @@
+import { createApp, onMounted, ref } from "vue";
+
+const App = {
+  setup() {
+    const health = ref("loading...");
+
+    onMounted(async () => {
+      try {
+        const response = await fetch("/api/v1/health");
+        const payload = await response.json();
+        health.value = payload?.ok ? "ok" : "unhealthy";
+      } catch {
+        health.value = "unreachable";
+      }
+    });
+
+    return {
+      health
+    };
+  },
+  template: `
+    <main style="font-family: sans-serif; max-width: 48rem; margin: 3rem auto; padding: 0 1rem;">
+      <h1>__APP_TITLE__</h1>
+      <p>Minimal starter shell is running.</p>
+      <p><strong>Health:</strong> {{ health }}</p>
+    </main>
+  `
+};
+
+createApp(App).mount("#app");

package/templates/base-shell/tests/client/smoke.vitest.js

@@ -0,0 +1,7 @@
+import { describe, expect, it } from "vitest";
+
+describe("__APP_NAME__ client smoke", () => {
+  it("runs vitest in __APP_NAME__", () => {
+    expect(true).toBe(true);
+  });
+});

package/templates/base-shell/tests/server/minimalShell.contract.test.js

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readdir, readFile } from "node:fs/promises";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const APP_ROOT = path.resolve(__dirname, "../..");
+
+const EXPECTED_RUNTIME_DEPENDENCIES = Object.freeze([
+  "@jskit-ai/app-scripts",
+  "fastify",
+  "vue"
+]);
+
+const EXPECTED_DEV_DEPENDENCIES = Object.freeze([
+  "@jskit-ai/config-eslint",
+  "@vitejs/plugin-vue",
+  "eslint",
+  "vite",
+  "vitest"
+]);
+
+const EXPECTED_TOP_LEVEL_ENTRIES = Object.freeze([
+  "README.md",
+  "app.scripts.config.mjs",
+  "bin",
+  "eslint.config.mjs",
+  "favicon.svg",
+  "framework",
+  "gitignore",
+  "index.html",
+  "package.json",
+  "server.js",
+  "server",
+  "src",
+  "tests",
+  "vite.config.mjs"
+]);
+
+async function readPackageJson() {
+  const packageJsonPath = path.join(APP_ROOT, "package.json");
+  const raw = await readFile(packageJsonPath, "utf8");
+  return JSON.parse(raw);
+}
+
+function sortStrings(values) {
+  return [...values].sort((left, right) => left.localeCompare(right));
+}
+
+function sortedKeys(record) {
+  return sortStrings(Object.keys(record || {}));
+}
+
+async function readTopLevelEntries() {
+  const entries = await readdir(APP_ROOT, { withFileTypes: true });
+  const ignored = new Set([
+    "node_modules",
+    "dist",
+    "coverage",
+    "test-results",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock"
+  ]);
+  return entries
+    .map((entry) => entry.name)
+    .filter((name) => !name.startsWith("."))
+    .filter((name) => !ignored.has(name));
+}
+
+test("minimal shell keeps strict dependency allowlist", async () => {
+  const packageJson = await readPackageJson();
+  assert.deepEqual(
+    sortedKeys(packageJson.dependencies),
+    [...EXPECTED_RUNTIME_DEPENDENCIES].sort((left, right) => left.localeCompare(right))
+  );
+  assert.deepEqual(
+    sortedKeys(packageJson.devDependencies),
+    [...EXPECTED_DEV_DEPENDENCIES].sort((left, right) => left.localeCompare(right))
+  );
+});
+
+test("starter shell keeps a strict top-level footprint", async () => {
+  const entries = await readTopLevelEntries();
+  assert.deepEqual(sortStrings(entries), sortStrings(EXPECTED_TOP_LEVEL_ENTRIES));
+});
+
+test("manifest scaffold exists with strict core-only defaults", async () => {
+  const manifestModule = await import(path.join(APP_ROOT, "framework/app.manifest.mjs"));
+  const manifest = manifestModule?.default;
+
+  assert.equal(manifest.manifestVersion, 1);
+  assert.equal(manifest.appId, "__APP_NAME__");
+  assert.equal(manifest.profileId, "web-saas-default");
+  assert.equal(manifest.mode, "strict");
+  assert.equal(manifest.enforceProfileRequired, true);
+  assert.deepEqual(manifest.optionalModulePacks, ["core"]);
+});

package/templates/base-shell/tests/server/smoke.test.js

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createServer } from "../../server.js";
+
+test("GET /api/v1/health returns ok payload", async () => {
+  const app = createServer();
+  const response = await app.inject({
+    method: "GET",
+    url: "/api/v1/health"
+  });
+
+  assert.equal(response.statusCode, 200);
+  assert.deepEqual(response.json(), {
+    ok: true,
+    app: "__APP_NAME__"
+  });
+
+  await app.close();
+});

package/templates/base-shell/vite.config.mjs

@@ -0,0 +1,29 @@
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+
+function toPositiveInt(value, fallback) {
+  const parsed = Number.parseInt(String(value || "").trim(), 10);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallback;
+}
+
+const devPort = toPositiveInt(process.env.VITE_DEV_PORT, 5173);
+const apiProxyTarget = String(process.env.VITE_API_PROXY_TARGET || "").trim() || "http://localhost:3000";
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    include: ["tests/client/**/*.vitest.js"]
+  },
+  server: {
+    port: devPort,
+    proxy: {
+      "/api": {
+        target: apiProxyTarget,
+        changeOrigin: true
+      }
+    }
+  }
+});