create-taserjs 0.1.11 → 0.2.0

package/src/core/scaffold-engine.ts

@@ -1,117 +1,142 @@
-import { copyFile, mkdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { collectBootBindings, resolveAddons } from "../addons/registry.js";
-import { nitroConfigTemplate, taserTsTemplate, viteConfigTemplate } from "../frameworks/index.js";
 import { installPackages, resolveUserAgent } from "./package-manager.js";
-import { writeProjectConfig } from "./project-config.js";
-import { resolvePackages } from "./resolve-packages.js";
 import { resolveDeployEntry, validateCombination } from "./targets.js";
-import { FRAMEWORK_ENTRIES } from "../frameworks/index.js";
-import type { ScaffoldContext, ScaffoldOptions, ScaffoldResult } from "./types.js";
+import type { ScaffoldOptions, ScaffoldResult } from "./types.js";
 import {
   contextTemplate,
   gitignoreTemplate,
-  healthRouteTemplate,
   indexRouteTemplate,
+  nitroConfigTemplate,
   packageJsonTemplate,
   rootLayoutTemplate,
+  staticRoutesGenTemplate,
+  taserConfigTemplate,
+  taserTsTemplate,
   tsconfigTemplate,
+  viteConfigTemplate,
 } from "../templates/base.js";
 
 async function write(filePath: string, contents: string): Promise<void> {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, contents, "utf8");
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, contents.trimStart(), "utf-8");
 }
 
 export async function scaffoldProject(options: ScaffoldOptions): Promise<ScaffoldResult> {
   const root = options.targetDir;
-  const preset = options.preset ?? "node-server";
-  const framework = options.framework ?? "none";
+  const preset = options.preset ?? "none";
 
-  // Guards direct/library callers; the CLI path is validated earlier in
-  // resolveScaffoldDefaults. Throws with a precise reason on impossible
-  // runtime × framework × deploy combinations.
-  const combination = validateCombination(options.runtime, framework, preset);
+  const combination = validateCombination(options.runtime, preset);
   if (!combination.ok) {
     throw new Error(combination.reason);
   }
 
-  const ctx: ScaffoldContext = {
-    projectName: options.projectName,
-    targetDir: root,
-    framework,
-    preset,
-    ...(options.runtime !== undefined ? { runtime: options.runtime } : {}),
-    ...(options.db ? { db: options.db, driver: options.driver } : {}),
-    ...(options.logger ? { logger: options.logger } : {}),
-    ...(options.validator ? { validator: options.validator } : {}),
+  const writtenFiles: string[] = [];
+  const trackedWrite = async (relPath: string, contents: string) => {
+    const fullPath = join(root, relPath);
+    await write(fullPath, contents);
+    writtenFiles.push(relPath);
   };
 
-  const addons = resolveAddons(ctx);
-  const packages = resolvePackages(ctx);
-  const bootBindings = collectBootBindings(ctx);
-  const frameworkEntry = FRAMEWORK_ENTRIES[framework];
-  const { entry: deployEntry } = resolveDeployEntry(ctx.preset ?? "node-server");
+  const addons = resolveAddons(options);
+  const bootBindings = collectBootBindings(options);
+  const { entry: deployEntry } = resolveDeployEntry(preset);
 
-  await write(
-    path.join(root, "package.json"),
-    packageJsonTemplate(options.projectName, packages.scripts),
-  );
-  await write(path.join(root, "tsconfig.json"), tsconfigTemplate());
-  await write(path.join(root, "vite.config.ts"), viteConfigTemplate(ctx.preset));
-  await write(path.join(root, ".gitignore"), gitignoreTemplate());
-  await write(path.join(root, "src/context.ts"), contextTemplate(bootBindings));
-  await write(path.join(root, "src/taser.ts"), taserTsTemplate());
-  await write(path.join(root, "src/routes/$.ts"), rootLayoutTemplate());
-  await write(path.join(root, "src/routes/index.get.ts"), indexRouteTemplate());
-  await write(path.join(root, "src/routes/health.get.ts"), healthRouteTemplate(ctx));
-
-  // Nitro's default preset is node-server — only emit an explicit config when
-  // the deployment target differs. Do not emit for preset "none".
-  if (ctx.preset !== "node-server" && ctx.preset !== "none") {
-    await write(path.join(root, "nitro.config.ts"), nitroConfigTemplate(deployEntry.id));
+  // Collect scripts & dependencies
+  const scripts: Record<string, string> = {};
+  if (deployEntry.startScript) {
+    scripts.start = deployEntry.startScript;
+  }
+
+  const dependencies: string[] = ["@taserjs/router", "@taserjs/runtime"];
+  const devDependencies: string[] = ["@taserjs/cli", "@taserjs/plugin", "typescript", "vite"];
+
+  for (const dep of deployEntry.devDeps) {
+    devDependencies.push(dep);
+  }
+
+  for (const addon of addons) {
+    dependencies.push(...addon.dependencies(options));
+    devDependencies.push(...addon.devDependencies(options));
+    if (addon.scripts) {
+      Object.assign(scripts, addon.scripts(options));
+    }
   }
 
+  // Override versions from packageVersions if provided
+  const formatDep = (pkg: string): string => {
+    const ver = options.packageVersions?.[pkg];
+    return ver ? `${pkg}@${ver}` : pkg;
+  };
+
+  const resolvedDeps = [...new Set(dependencies)].map(formatDep);
+  const resolvedDevDeps = [...new Set(devDependencies)].map(formatDep);
+
+  // 1. package.json
+  await trackedWrite("package.json", packageJsonTemplate(options.projectName, scripts));
+
+  // 2. tsconfig.json
+  await trackedWrite("tsconfig.json", tsconfigTemplate());
+
+  // 3. .gitignore
+  await trackedWrite(".gitignore", gitignoreTemplate());
+
+  // 4. taserjs.config.ts
+  await trackedWrite("taserjs.config.ts", taserConfigTemplate());
+
+  // 5. vite.config.ts
+  await trackedWrite("vite.config.ts", viteConfigTemplate(preset));
+
+  // 6. nitro.config.ts (if preset is selected)
+  if (preset !== "none") {
+    await trackedWrite("nitro.config.ts", nitroConfigTemplate(preset));
+  }
+
+  // 7. Platform files (e.g. wrangler.jsonc)
   await Promise.all(
-    deployEntry.files.map((file) =>
-      write(
-        path.join(root, file.name),
+    deployEntry.files.map(async (file) => {
+      const content =
         typeof file.content === "function"
           ? file.content({ projectName: options.projectName })
-          : file.content,
-      ),
-    ),
+          : file.content;
+      await trackedWrite(file.name, content);
+    }),
   );
 
-  const serverEntry = frameworkEntry.serverEntry;
-  if (serverEntry) {
-    await write(path.join(root, serverEntry.fileName), serverEntry.content);
-  }
+  // 8. src/context.ts
+  await trackedWrite("src/context.ts", contextTemplate(bootBindings));
 
+  // 9. src/taser.ts
+  await trackedWrite("src/taser.ts", taserTsTemplate());
+
+  // 10. Routes: src/routes/index.get.ts & src/routes/$.ts
+  await trackedWrite("src/routes/index.get.ts", indexRouteTemplate());
+  await trackedWrite("src/routes/$.ts", rootLayoutTemplate());
+
+  // 12. Apply Addons (custom routes, db schemas, configs)
   await Promise.all(
     addons.map(async (addon) => {
-      await addon.apply(ctx, (filePath, contents) => write(path.join(root, filePath), contents));
+      await addon.apply(options, async (relPath, contents) => {
+        await trackedWrite(relPath, contents);
+      });
     }),
   );
 
-  try {
-    await copyFile(path.join(root, ".env.example"), path.join(root, ".env"));
-  } catch {
-    // .env.example was not created
-  }
-
-  await writeProjectConfig(root, ctx);
+  // 13. Static routes.gen.ts starter manifest
+  await trackedWrite("src/.taserjs/routes.gen.ts", staticRoutesGenTemplate());
 
-  if (options.skipInstall) {
-    return ctx as ScaffoldResult;
+  // Install dependencies if not skipped
+  if (!options.skipInstall) {
+    const agent = options.agent ?? resolveUserAgent();
+    await installPackages(agent, root, {
+      dependencies: resolvedDeps,
+      devDependencies: resolvedDevDeps,
+    });
   }
 
-  const agent = options.agent ?? resolveUserAgent();
-  await installPackages(agent, root, {
-    dependencies: packages.dependencies,
-    devDependencies: packages.devDependencies,
-  });
-
-  return ctx as ScaffoldResult;
+  return {
+    ...options,
+    files: writtenFiles,
+  };
 }

package/src/core/targets.ts

@@ -1,32 +1,20 @@
-/**
- * Registry for the three scaffold dimensions — runtime, framework, deploy —
- * plus the compatibility rules between them.
- *
- * Dependency direction: deploy implies the runtime family; the effective
- * runtime constrains which frameworks can run. `--runtime` is an override
- * available only where it is meaningful (self-hosted node-family targets).
- */
-import { DEPLOY_TARGETS, type DeployTarget, type Framework, type Runtime } from "./types.js";
+import { DEPLOY_TARGETS, type DeployTarget, type Runtime } from "./types.js";
 
-export type PlatformFile = {
+export interface PlatformFile {
   name: string;
   content: string | ((ctx: { projectName: string }) => string);
-};
+}
 
-export type DeployEntry = {
+export interface DeployEntry {
   id: DeployTarget;
-  /** Runtime this target builds for ("workerd" = Cloudflare's V8 runtime). */
   impliedRuntime: Runtime | "workerd";
-  /** Whether the built output is a long-running server you start locally. */
   selfHosted: boolean;
-  /** `start` script value; null for platform-deployed targets. */
   startScript: string | null;
-  /** Runtime/platform tooling devDependencies beyond the base set. */
   devDeps: string[];
   files: PlatformFile[];
-};
+}
 
-const NODE_START = "node .output/server/index.mjs";
+const NITRO_NODE_START = "node .output/server/index.mjs";
 
 export const DEPLOY_ENTRIES: Record<DeployTarget, DeployEntry> = {
   none: {
@@ -34,23 +22,23 @@ export const DEPLOY_ENTRIES: Record<DeployTarget, DeployEntry> = {
     impliedRuntime: "node",
     selfHosted: true,
     startScript: "node dist/serve.mjs",
-    devDeps: [],
+    devDeps: ["srvx"],
     files: [],
   },
   "node-server": {
     id: "node-server",
     impliedRuntime: "node",
     selfHosted: true,
-    startScript: NODE_START,
-    devDeps: [],
+    startScript: NITRO_NODE_START,
+    devDeps: ["nitro"],
     files: [],
   },
   "node-cluster": {
     id: "node-cluster",
     impliedRuntime: "node",
     selfHosted: true,
-    startScript: NODE_START,
-    devDeps: [],
+    startScript: NITRO_NODE_START,
+    devDeps: ["nitro"],
     files: [],
   },
   bun: {
@@ -58,7 +46,7 @@ export const DEPLOY_ENTRIES: Record<DeployTarget, DeployEntry> = {
     impliedRuntime: "bun",
     selfHosted: true,
     startScript: "bun .output/server/index.mjs",
-    devDeps: ["@types/bun"],
+    devDeps: ["nitro", "@types/bun"],
     files: [],
   },
   "deno-server": {
@@ -66,7 +54,7 @@ export const DEPLOY_ENTRIES: Record<DeployTarget, DeployEntry> = {
     impliedRuntime: "deno",
     selfHosted: true,
     startScript: "deno run -A .output/server/index.mjs",
-    devDeps: [],
+    devDeps: ["nitro"],
     files: [],
   },
   "deno-deploy": {
@@ -74,7 +62,7 @@ export const DEPLOY_ENTRIES: Record<DeployTarget, DeployEntry> = {
     impliedRuntime: "deno",
     selfHosted: false,
     startScript: null,
-    devDeps: [],
+    devDeps: ["nitro"],
     files: [],
   },
   "cloudflare-module": {
@@ -82,7 +70,7 @@ export const DEPLOY_ENTRIES: Record<DeployTarget, DeployEntry> = {
     impliedRuntime: "workerd",
     selfHosted: false,
     startScript: null,
-    devDeps: ["wrangler", "@cloudflare/workers-types"],
+    devDeps: ["nitro", "wrangler", "@cloudflare/workers-types"],
     files: [
       {
         name: "wrangler.jsonc",
@@ -105,7 +93,7 @@ export const DEPLOY_ENTRIES: Record<DeployTarget, DeployEntry> = {
     impliedRuntime: "node",
     selfHosted: false,
     startScript: null,
-    devDeps: ["@vercel/node"],
+    devDeps: ["nitro", "@vercel/node"],
     files: [],
   },
   "aws-lambda": {
@@ -113,7 +101,7 @@ export const DEPLOY_ENTRIES: Record<DeployTarget, DeployEntry> = {
     impliedRuntime: "node",
     selfHosted: false,
     startScript: null,
-    devDeps: ["@types/aws-lambda"],
+    devDeps: ["nitro", "@types/aws-lambda"],
     files: [],
   },
   netlify: {
@@ -121,49 +109,40 @@ export const DEPLOY_ENTRIES: Record<DeployTarget, DeployEntry> = {
     impliedRuntime: "node",
     selfHosted: false,
     startScript: null,
-    devDeps: [],
+    devDeps: ["nitro"],
     files: [],
   },
 };
 
-/** Runtimes a `--runtime` override may select per self-hosted deploy target. */
 const RUNTIME_OVERRIDES: Partial<Record<DeployTarget, readonly Runtime[]>> = {
   none: ["node", "bun"],
   "node-server": ["node", "bun"],
   "node-cluster": ["node", "bun"],
 };
 
-export const DEFAULT_DEPLOY: DeployTarget = "node-server";
-export const DEFAULT_FRAMEWORK: Framework = "none";
+export const DEFAULT_DEPLOY: DeployTarget = "none";
 
 export function isCuratedDeploy(value: string): value is DeployTarget {
   return (DEPLOY_TARGETS as readonly string[]).includes(value);
 }
 
-/**
- * Resolves any preset id to its emission entry. Curated ids come from the
- * registry; unknown strings pass through to Nitro verbatim as non-self-hosted
- * node-family targets.
- */
 export function resolveDeployEntry(id: string): { entry: DeployEntry; curated: boolean } {
   if (isCuratedDeploy(id)) {
     return { entry: DEPLOY_ENTRIES[id], curated: true };
   }
   return {
     entry: {
-      // Cast: passthrough ids are valid Nitro PresetNameInputs by contract.
       id: id as DeployTarget,
       impliedRuntime: "node",
       selfHosted: false,
       startScript: null,
-      devDeps: [],
+      devDeps: ["nitro"],
       files: [],
     },
     curated: false,
   };
 }
 
-/** Runtime overrides permitted for a deploy target; empty = no override. */
 export function allowedRuntimeOverrides(id: DeployTarget): readonly Runtime[] {
   return RUNTIME_OVERRIDES[id] ?? [];
 }
@@ -171,15 +150,8 @@ export function allowedRuntimeOverrides(id: DeployTarget): readonly Runtime[] {
 export type CombinationError = { ok: false; reason: string };
 export type CombinationOk = { ok: true; runtime: Runtime | "workerd" };
 
-/**
- * Validates a runtime × framework × deploy combination.
- *
- * @param runtimeOverride explicit `--runtime` selection, if any
- * @param deploy preset id (curated or passthrough)
- */
 export function validateCombination(
   runtimeOverride: Runtime | undefined,
-  framework: Framework,
   deploy: string,
 ): CombinationOk | CombinationError {
   const { entry } = resolveDeployEntry(deploy);
@@ -199,13 +171,5 @@ export function validateCombination(
   }
 
   const effective = runtimeOverride ?? entry.impliedRuntime;
-
-  if ((framework === "express" || framework === "fastify") && effective !== "node") {
-    return {
-      ok: false,
-      reason: `Framework "${framework}" requires the Node runtime, but deploy target "${entry.id}" implies "${String(effective)}".`,
-    };
-  }
-
   return { ok: true, runtime: effective };
 }

package/src/core/types.ts

@@ -1,18 +1,8 @@
 import type { Agent } from "package-manager-detector";
 
-/** Host framework layered on top of pure Taser.js pass-through dispatch. */
-export type Framework = "none" | "hono" | "express" | "fastify";
-
-export const FRAMEWORKS: readonly Framework[] = ["none", "hono", "express", "fastify"];
-
 export type Runtime = "node" | "bun" | "deno";
-
 export const RUNTIMES: readonly Runtime[] = ["node", "bun", "deno"];
 
-/**
- * Deployment target. Values are Nitro preset ids (see `nitro/config`
- * PresetNameInput) so `--preset` passes straight through to Nitro.
- */
 export type DeployTarget =
   | "none"
   | "node-server"
@@ -39,60 +29,35 @@ export const DEPLOY_TARGETS: readonly DeployTarget[] = [
 ];
 
 export type DbOdm = "drizzle" | "prisma" | "kysely";
-
 export const DB_ODMS: readonly DbOdm[] = ["drizzle", "prisma", "kysely"];
 
 export type DbDriver = "postgres" | "sqlite" | "mysql";
-
 export const DB_DRIVERS: readonly DbDriver[] = ["postgres", "sqlite", "mysql"];
-
 export const DEFAULT_DB_DRIVER: DbDriver = "sqlite";
 
 export type LoggerId = "pino" | "winston";
-
 export const LOGGERS: readonly LoggerId[] = ["pino", "winston"];
 
 export type ValidatorId = "zod" | "arktype" | "valibot";
-
 export const VALIDATORS: readonly ValidatorId[] = ["zod", "arktype", "valibot"];
 
-export type PackageGroups = {
-  dependencies: string[];
-  devDependencies: string[];
-  scripts: Record<string, string>;
-};
-
-export type ScaffoldContext = {
+export interface ScaffoldContext {
   projectName: string;
   targetDir: string;
-  /** Host framework; "none" is pure Taser.js pass-through dispatch. Defaults to "none". */
-  framework?: Framework;
-  /** Deployment target — a Nitro preset id. Defaults to "node-server". */
-  preset?: DeployTarget;
-  /** Set only when explicitly overriding the runtime implied by the preset. */
-  runtime?: Runtime;
-  db?: DbOdm;
-  driver?: DbDriver;
-  logger?: LoggerId;
-  validator?: ValidatorId;
-};
-
-export type ScaffoldOptions = ScaffoldContext & {
-  skipInstall?: boolean;
-  agent?: Agent;
-};
-
-export type ScaffoldResult = ScaffoldContext;
-
-export type CapabilitiesCatalog = {
-  frameworks: Framework[];
-  deployTargets: DeployTarget[];
-  runtimes: Runtime[];
-  db: {
-    odms: DbOdm[];
-    drivers: DbDriver[];
-    defaultDriver: DbDriver;
-  };
-  loggers: LoggerId[];
-  validators: ValidatorId[];
-};
+  preset?: DeployTarget | undefined;
+  runtime?: Runtime | undefined;
+  db?: DbOdm | undefined;
+  driver?: DbDriver | undefined;
+  logger?: LoggerId | undefined;
+  validator?: ValidatorId | undefined;
+  packageVersions?: Record<string, string> | undefined;
+}
+
+export interface ScaffoldOptions extends ScaffoldContext {
+  skipInstall?: boolean | undefined;
+  agent?: Agent | undefined;
+}
+
+export interface ScaffoldResult extends ScaffoldContext {
+  files: string[];
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./core/types.js";
+export * from "./core/scaffold-engine.js";
+export * from "./core/package-manager.js";
+export * from "./core/targets.js";
+export * from "./addons/types.js";
+export * from "./addons/registry.js";
+export * from "./commands/create.js";
+export * from "./cli.js";