create-tilcayo-app 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# create-tilcayo-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Create a Tilcayo API with an interactive setup wizard:
+
+```sh
+create-tilcayo-app
+```
+
+Once published to your registry, bootstrap without a global install:
+
+```sh
+npm create tilcayo-app@latest
+pnpm create tilcayo-app
+yarn create tilcayo-app
+```
+
+For local development in the Tilcayo repository, build the workspace and run
+`node packages/create-tilcayo-app/dist/bin.js my-api`, or link this package to expose
+`create-tilcayo-app` on PATH.
+
+```sh
+create-tilcayo-app my-api --type api --auth --package-manager npm --yes
+create-tilcayo-app tiny-api --type minimal --no-auth --no-install --yes
+```
+
+The wizard offers project name, package manager (npm, pnpm, or Yarn), application
+type, and authentication. Use the arrow keys and Enter to choose from colored
+menus; project name remains a text field. Ctrl+C cancels before files are created.
+`api` includes MongoDB-backed note CRUD; `minimal`
+includes a health endpoint. Enabling authentication adds MongoDB to either type.
+Noninteractive runs use defaults for omitted options. Existing paths are refused.
+
+Generated projects contain controllers, routes, models, services, validators,
+separate app and startup modules, TypeScript configuration, `.gitignore`,
+`.env.example`, and a private `.env`. Authentication gets independent random
+secrets in `.env`; the example file leaves secrets blank.
+
+Setup installs dependencies and builds unless `--no-install` is supplied. The
+selected package manager must be installed. Running the creator from a built
+Tilcayo source checkout automatically links the local framework packages and
+their shared Zod and Mongoose dependencies. Keep that checkout available while
+developing the generated app. The published creator uses registry versions of
+`@tilcayo/core`, `@tilcayo/auth`, and `@tilcayo/cli` instead.
+Installation failures retain the generated project and report recovery steps.
+MongoDB must be running before starting an API that uses it.
+
+Inside the generated project, use `tilcayo dev`, `tilcayo build`, `tilcayo start`,
+and `tilcayo routes:list`. If the CLI is installed only in the project, invoke
+it through `npx tilcayo`, `pnpm exec tilcayo`, or `yarn exec tilcayo`.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { stdin, stdout } from "node:process";
+import { cancel, intro, isCancel, select, text } from "@clack/prompts";
+import color from "picocolors";
+import { generateApp, installApp } from "./index.js";
+import { help, parseOptions, validateOptions } from "./options.js";
+function answer(value) {
+    if (isCancel(value)) {
+        cancel("Setup cancelled. No files were created.");
+        process.exit(130);
+    }
+    return value;
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(help);
+        return;
+    }
+    const { options, missing, yes } = parseOptions(args);
+    if (!yes && stdin.isTTY && stdout.isTTY) {
+        intro(color.bgCyan(color.black(" Create Tilcayo App ")));
+        if (missing.has("name"))
+            options.name = answer(await text({
+                message: "Project name",
+                placeholder: options.name,
+                defaultValue: options.name,
+                validate(value) {
+                    try {
+                        validateOptions({ ...options, name: value?.trim() || options.name });
+                    }
+                    catch (error) {
+                        return error instanceof Error ? error.message : "Invalid project name.";
+                    }
+                },
+            })).trim();
+        if (missing.has("packageManager"))
+            options.packageManager = answer(await select({
+                message: "Package manager (use arrow keys, Enter to select)",
+                initialValue: options.packageManager,
+                options: [
+                    { value: "npm", label: color.red("npm") },
+                    { value: "pnpm", label: color.yellow("pnpm") },
+                    { value: "yarn", label: color.cyan("yarn") },
+                ],
+            }));
+        if (missing.has("type"))
+            options.type = answer(await select({
+                message: "Application type",
+                initialValue: options.type,
+                options: [
+                    { value: "api", label: color.green("API"), hint: "MongoDB with sample CRUD routes" },
+                    { value: "minimal", label: color.magenta("Minimal"), hint: "Health-check endpoint only" },
+                ],
+            }));
+        if (missing.has("auth"))
+            options.auth = answer(await select({
+                message: "Include authentication?",
+                initialValue: options.auth,
+                options: [
+                    { value: true, label: color.green("Yes"), hint: "Register, login, refresh and logout; requires MongoDB" },
+                    { value: false, label: color.yellow("No"), hint: "Start without authentication" },
+                ],
+            }));
+    }
+    validateOptions(options);
+    const target = await generateApp(options);
+    console.log(`Created ${target}`);
+    if (options.install) {
+        console.log(`Installing dependencies with ${options.packageManager} and building the API...`);
+        await installApp(target, options.packageManager);
+    }
+    console.log(`\nNext:\n  cd ${options.name}`);
+    if (!options.install)
+        console.log(`  ${options.packageManager} install`);
+    const cli = options.packageManager === "npm" ? "npx tilcayo" : `${options.packageManager} exec tilcayo`;
+    console.log(`  ${cli} dev\n\nWith Tilcayo on PATH, use tilcayo dev directly.`);
+    if (options.type === "api" || options.auth)
+        console.log("Start MongoDB or update MONGODB_URI in .env before starting the API.");
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : "Unable to create application.");
+    process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { type StarterOptions } from "./options.js";
+export type { StarterOptions } from "./options.js";
+export declare function generateApp(options: StarterOptions, root?: string): Promise<string>;
+export declare function installApp(target: string, manager: StarterOptions["packageManager"]): Promise<void>;

package/dist/index.js

@@ -0,0 +1,86 @@
+import { mkdir, writeFile, readFile, access } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { make } from "@tilcayo/cli";
+import { templates } from "./templates.js";
+import { validateOptions } from "./options.js";
+async function localDependencies(target, options) {
+    const checkout = fileURLToPath(new URL("../../../", import.meta.url));
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(path.join(checkout, "package.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+    if (manifest.name !== "tilcayo" || manifest.private !== true || !Array.isArray(manifest.workspaces) || !manifest.workspaces.includes("packages/*"))
+        return {};
+    const dependencies = {};
+    for (const name of ["core", "cli", ...(options.auth ? ["auth"] : [])]) {
+        const directory = path.join(checkout, "packages", name);
+        const pkg = JSON.parse(await readFile(path.join(directory, "package.json"), "utf8"));
+        if (pkg.name !== `@tilcayo/${name}`)
+            throw new Error(`Invalid local Tilcayo package: ${directory}`);
+        try {
+            await access(path.join(directory, "dist/index.js"));
+        }
+        catch {
+            throw new Error(`Build the Tilcayo workspace before creating an application: ${directory}/dist/index.js is missing.`);
+        }
+        const relative = path.relative(target, directory).split(path.sep).join("/");
+        dependencies[name] = `${options.packageManager === "npm" ? "file" : "link"}:${relative}`;
+    }
+    const require = createRequire(path.join(checkout, "packages/core/package.json"));
+    for (const name of ["zod", ...(options.type === "api" || options.auth ? ["mongoose"] : [])]) {
+        const directory = path.dirname(require.resolve(`${name}/package.json`));
+        const relative = path.relative(target, directory).split(path.sep).join("/");
+        dependencies[name] = `${options.packageManager === "npm" ? "file" : "link"}:${relative}`;
+    }
+    return dependencies;
+}
+export async function generateApp(options, root = process.cwd()) {
+    validateOptions(options);
+    const target = path.resolve(root, options.name);
+    const sources = templates(options, await localDependencies(target, options));
+    try {
+        await mkdir(target);
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new Error(`Target already exists: ${target}. Choose a new project name.`);
+        throw error;
+    }
+    for (const [filename, source] of Object.entries(sources)) {
+        const destination = path.join(target, filename);
+        await mkdir(path.dirname(destination), { recursive: true });
+        await writeFile(destination, source, { flag: "wx", ...(filename === ".env" ? { mode: 0o600 } : {}) });
+    }
+    if (options.type === "api")
+        await make(["make:resource", "Note", "title:string", "content?:string"], target);
+    if (options.auth)
+        await make(["make:auth"], target);
+    return target;
+}
+function run(command, args, cwd, shell = false) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, stdio: "inherit", shell, windowsHide: true });
+        child.once("error", reject);
+        child.once("exit", (code, signal) => code === 0 ? resolve() : reject(new Error(`${command} failed (${signal ?? code}).`)));
+    });
+}
+export async function installApp(target, manager) {
+    if (!["npm", "pnpm", "yarn"].includes(manager))
+        throw new Error("Unsupported package manager.");
+    try {
+        // Both the command and its arguments are fixed, not user-supplied shell text.
+        await run(manager, ["install"], target, process.platform === "win32");
+        const require = createRequire(path.join(target, "package.json"));
+        const cli = path.join(path.dirname(require.resolve("@tilcayo/cli")), "bin.js");
+        await run(process.execPath, [cli, "build"], target);
+    }
+    catch {
+        throw new Error(`Project created at ${target}, but dependency installation or build failed. Check that ${manager} is installed and Tilcayo packages are available in your registry, then run ${manager} install and the Tilcayo build command inside the project.`);
+    }
+}

package/dist/options.d.ts

@@ -0,0 +1,14 @@
+export interface StarterOptions {
+    name: string;
+    packageManager: "npm" | "pnpm" | "yarn";
+    type: "api" | "minimal";
+    auth: boolean;
+    install: boolean;
+}
+export declare const help = "Usage: create-tilcayo-app [project-name] [options]\n\n  --package-manager npm|pnpm|yarn\n  --type api|minimal      MongoDB CRUD API or minimal health-check API\n  --auth / --no-auth      Include JWT authentication (requires MongoDB)\n  --no-install           Generate files without installing dependencies\n  --yes                  Use defaults for unanswered choices\n  --help                 Show this help\n\nDefaults: my-api, npm, api, no authentication, install dependencies.\nInteractive terminals prompt for missing choices. Automation uses defaults.\nExisting directories are never overwritten.";
+export declare function validateOptions(options: StarterOptions): void;
+export declare function parseOptions(args: string[]): {
+    options: StarterOptions;
+    missing: Set<string>;
+    yes: boolean;
+};

package/dist/options.js

@@ -0,0 +1,73 @@
+export const help = `Usage: create-tilcayo-app [project-name] [options]
+
+  --package-manager npm|pnpm|yarn
+  --type api|minimal      MongoDB CRUD API or minimal health-check API
+  --auth / --no-auth      Include JWT authentication (requires MongoDB)
+  --no-install           Generate files without installing dependencies
+  --yes                  Use defaults for unanswered choices
+  --help                 Show this help
+
+Defaults: my-api, npm, api, no authentication, install dependencies.
+Interactive terminals prompt for missing choices. Automation uses defaults.
+Existing directories are never overwritten.`;
+export function validateOptions(options) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(options.name) || options.name.length > 214 || ["node_modules", "con", "prn", "aux", "nul"].includes(options.name) || /^(com|lpt)[0-9]$/.test(options.name)) {
+        throw new Error("Use a project name containing lowercase letters, numbers, and hyphens (not a path or reserved system name).");
+    }
+    if (!["npm", "pnpm", "yarn"].includes(options.packageManager))
+        throw new Error("Package manager must be npm, pnpm, or yarn.");
+    if (!["api", "minimal"].includes(options.type))
+        throw new Error("Application type must be api or minimal.");
+    if (typeof options.auth !== "boolean" || typeof options.install !== "boolean")
+        throw new Error("Authentication and install choices must be booleans.");
+}
+export function parseOptions(args) {
+    const options = { name: "my-api", packageManager: "npm", type: "api", auth: false, install: true };
+    const missing = new Set(["name", "packageManager", "type", "auth"]);
+    const seen = new Set();
+    let yes = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith("-")) {
+            if (!missing.has("name"))
+                throw new Error("Provide only one project name.");
+            options.name = arg;
+            missing.delete("name");
+            continue;
+        }
+        const key = arg === "--no-auth" ? "--auth" : arg;
+        if (seen.has(key))
+            throw new Error(`Duplicate or conflicting option: ${arg}`);
+        seen.add(key);
+        if (arg === "--yes" || arg === "-y") {
+            yes = true;
+            continue;
+        }
+        if (arg === "--no-install") {
+            options.install = false;
+            continue;
+        }
+        if (arg === "--auth" || arg === "--no-auth") {
+            options.auth = arg === "--auth";
+            missing.delete("auth");
+            continue;
+        }
+        if (arg === "--package-manager" || arg === "--type") {
+            const value = args[++i];
+            if (!value || value.startsWith("-"))
+                throw new Error(`Missing value for ${arg}.`);
+            if (arg === "--package-manager") {
+                options.packageManager = value;
+                missing.delete("packageManager");
+            }
+            else {
+                options.type = value;
+                missing.delete("type");
+            }
+            continue;
+        }
+        throw new Error(`Unknown option: ${arg}. Run create-tilcayo-app --help.`);
+    }
+    validateOptions(options);
+    return { options, missing, yes };
+}

package/dist/templates.d.ts

@@ -0,0 +1,2 @@
+import type { StarterOptions } from "./options.js";
+export declare function templates(options: StarterOptions, localPackages?: Record<string, string>): Record<string, string>;

package/dist/templates.js

@@ -0,0 +1,99 @@
+import { randomBytes } from "node:crypto";
+export function templates(options, localPackages = {}) {
+    const mongo = options.type === "api" || options.auth;
+    const json = (value) => JSON.stringify(value, null, 2) + "\n";
+    const env = `# Server\nPORT=9149\n${mongo ? `\n# Database\nMONGODB_URI=mongodb://127.0.0.1:27017/${options.name.replaceAll("-", "_")}\n` : ""}`;
+    return {
+        "package.json": json({
+            name: options.name, version: "0.0.1", private: true, type: "module",
+            engines: { node: ">=22.9.0" },
+            tilcayo: { database: mongo ? "mongo" : "none", type: options.type, packageManager: options.packageManager },
+            scripts: { dev: "tilcayo dev", build: "tilcayo build", start: "tilcayo start", routes: "tilcayo routes:list" },
+            dependencies: { "@tilcayo/core": localPackages.core ?? "^0.0.1", ...(options.auth ? { "@tilcayo/auth": localPackages.auth ?? "^0.0.1" } : {}), ...(mongo ? { mongoose: localPackages.mongoose ?? "^9.10.2" } : {}), zod: localPackages.zod ?? "^4.0.0" },
+            devDependencies: { "@tilcayo/cli": localPackages.cli ?? "^0.0.1", "@types/node": "^26.6.3", typescript: "^7.0.2", nodemon: "^3.1.14" },
+        }),
+        "tsconfig.json": json({ compilerOptions: { target: "ES2022", module: "NodeNext", moduleResolution: "NodeNext", strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, rootDir: "src", outDir: "dist", types: ["node"] }, include: ["src/**/*.ts"] }),
+        ".gitignore": "node_modules/\ndist/\n.env\n.env.*\n!.env.example\n*.log\n.DS_Store\n",
+        ".env.example": env + (options.auth ? "\n# Authentication - use private values from .env\nAUTH_ACCESS_SECRET=\nAUTH_REFRESH_SECRET=\n" : ""),
+        ".env": env + (options.auth ? `\n# Authentication - keep these secrets private\nAUTH_ACCESS_SECRET=${randomBytes(32).toString("hex")}\nAUTH_REFRESH_SECRET=${randomBytes(32).toString("hex")}\n` : ""),
+        ...(options.packageManager === "yarn" ? { ".yarnrc.yml": "nodeLinker: node-modules\n" } : {}),
+        "src/config.ts": `const port = Number(process.env.PORT ?? 9149);
+if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error("PORT must be an integer between 0 and 65535.");
+
+export const config = {
+  port,
+${mongo ? '  mongoUri: process.env.MONGODB_URI ?? "",\n' : ""}};
+`,
+        "src/app.ts": `import { createApp, requestId, securityHeaders } from "@tilcayo/core";
+import healthRoutes from "./routes/health.routes.js";
+${options.type === "api" ? 'import notesRoutes from "./routes/notes.routes.js";\n' : ""}${options.auth ? 'import authRoutes from "./routes/auth.routes.js";\n' : ""}
+const app = createApp({ middleware: [requestId(), securityHeaders()] });
+app.routes(healthRoutes);
+${options.type === "api" ? "app.routes(notesRoutes);\n" : ""}${options.auth ? "app.routes(authRoutes);\n" : ""}
+export default app;
+`,
+        "src/index.ts": `${mongo ? 'import { connectMongo, disconnectMongo } from "@tilcayo/core";\n' : ""}
+async function main() {
+  const { config } = await import("./config.js");
+  const { default: app } = await import("./app.js");
+${mongo ? "  await connectMongo(config.mongoUri);\n" : ""}  const server = app.listen(config.port);
+  const shutdown = () => {
+    const timeout = setTimeout(() => process.exit(1), 10_000);
+    timeout.unref();
+    server.close(() => {
+${mongo ? "      void disconnectMongo().then(() => process.exit(0), () => process.exit(1));" : "      process.exit(0);"}
+    });
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+}
+
+main().catch(() => {
+  console.error("Unable to start the API. Check .env configuration${mongo ? ", MongoDB connectivity" : ""}${options.auth ? ", and distinct auth secrets of at least 32 bytes each" : ""}.");
+  process.exitCode = 1;
+});
+`,
+        "src/controllers/health.controller.ts": `import type { TilcayoContext } from "@tilcayo/core";
+
+export const health = (ctx: TilcayoContext) => ctx.response.success({ status: "ok" });
+`,
+        "src/routes/health.routes.ts": `import { defineRoutes } from "@tilcayo/core";
+import { health } from "../controllers/health.controller.js";
+
+export default defineRoutes((router) => {
+  router.get("/health", health);
+});
+`,
+        "src/models/.gitkeep": "",
+        "src/services/.gitkeep": "",
+        "src/validators/.gitkeep": "",
+        "README.md": `# ${options.name}
+
+Tilcayo ${options.type === "api" ? "MongoDB CRUD" : "minimal"} API${options.auth ? " with JWT authentication" : ""}.
+${Object.keys(localPackages).length ? "\nTilcayo dependencies link to your local framework checkout. Keep that checkout available and rebuild its packages after framework changes. Replace these links with published versions before moving or sharing this application.\n" : ""}
+
+Use Node.js 22.9+ and ${options.packageManager}. A local .env has been created${options.auth ? " with distinct random auth secrets" : ""}. Keep it private; .env.example contains shareable settings.
+${mongo ? "\nStart MongoDB locally or set MONGODB_URI in .env to your connection string.\n" : ""}
+Install dependencies if you skipped setup:
+
+\`\`\`sh
+${options.packageManager} install
+\`\`\`
+
+With the Tilcayo CLI on PATH:
+
+\`\`\`sh
+tilcayo dev
+tilcayo build
+tilcayo start
+tilcayo routes:list
+\`\`\`
+
+If the CLI is only installed locally, use ${options.packageManager === "npm" ? "npx tilcayo" : `${options.packageManager} exec tilcayo`} with the same commands. Package scripts also expose dev, build, start, and routes.
+
+GET /health returns the application status. The default port is 9149.
+${options.type === "api" ? "\nThe /notes resource includes GET, POST, GET /:id, PUT /:id, and DELETE /:id. Create a note with JSON {\"title\":\"First note\",\"content\":\"Hello\"}. These sample routes are public.\n" : ""}${options.auth ? "\nAuth routes: POST /api/auth/register, /login, /refresh, /logout; GET /api/auth/me. Register with name, email, and password. Send the access token as Authorization: Bearer <token>. Protect other routes with auth.middleware.\n" : ""}
+Register generated routes in src/app.ts. Database connection and server startup live in src/index.ts. Rebuild after changing routes before using routes:list. ${!mongo ? "To add MongoDB resources or auth later, set tilcayo.database to mongo, add the required packages and environment keys, and connect MongoDB in src/index.ts." : ""}
+`,
+    };
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "create-tilcayo-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Create a complete Tilcayo API application",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "create-tilcayo-app": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.9.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "@tilcayo/cli": "^0.0.1",
+    "picocolors": "^1.1.1"
+  }
+}