create-asaje-go-vue 0.2.6 → 0.2.8

package/README.md

@@ -44,6 +44,14 @@ npx -p create-asaje-go-vue@latest asaje doctor ./my-app
 npx -p create-asaje-go-vue@latest asaje publish
 ```
 
+### Update an existing project from the template
+
+```bash
+npx -p create-asaje-go-vue@latest asaje update ./my-app --dry-run
+npx -p create-asaje-go-vue@latest asaje update ./my-app --yes
+npx -p create-asaje-go-vue@latest asaje update ./my-app --include admin/src/stores/session.ts,admin/src/services/http/session.ts
+```
+
 ### Provision Railway resources
 
 ```bash
@@ -58,6 +66,13 @@ npx -p create-asaje-go-vue@latest asaje sync-railway-env ./my-app
 npx -p create-asaje-go-vue@latest asaje sync-railway-env ./my-app --dry-run
 ```
 
+### Destroy Railway resources
+
+```bash
+npx -p create-asaje-go-vue@latest asaje destroy-railway ./my-app
+npx -p create-asaje-go-vue@latest asaje destroy-railway ./my-app --scope project --yes
+```
+
 ## What `create` does
 
 - clones the boilerplate from GitHub with `degit`
@@ -89,6 +104,16 @@ npx -p create-asaje-go-vue@latest asaje sync-railway-env ./my-app --dry-run
 - runs `npm run pack:dry-run`
 - prints the final manual npm release steps
 
+## What `asaje update` does
+
+- validates the target project structure
+- reads the template repository and branch from `asaje.config.json` when available
+- clones the latest template into a temporary directory
+- overwrites a safe set of boilerplate-managed files such as Railway config, Dockerfiles, generated Swagger docs, and `.env.example` files
+- supports `--include` for explicitly overwriting extra files or directories from the template, such as `admin/src/stores/session.ts`
+- supports `--dry-run` to preview which files would be updated
+- updates `asaje.config.json` with the template repository and branch used for the update
+
 ## What `asaje setup-railway` does
 
 - validates the target project structure
@@ -111,6 +136,15 @@ npx -p create-asaje-go-vue@latest asaje sync-railway-env ./my-app --dry-run
 - syncs variables for `api`, `realtime-gateway`, and `admin` without provisioning infra resources
 - supports `--dry-run` to preview variable changes without applying them
 
+## What `asaje destroy-railway` does
+
+- validates the target project structure
+- checks that the Railway CLI is installed and authenticated
+- deletes either the linked Railway environment or the whole Railway project
+- supports `--scope environment` (default) and `--scope project`
+- supports `--dry-run` to preview the destructive action without applying it
+- removes the local `asaje.railway.json` manifest after a successful deletion
+
 ## Useful flags
 
 ```bash
@@ -121,9 +155,12 @@ node ./bin/asaje.js start ../my-app --yes --profile frontend-only
 node ./bin/asaje.js start ../my-app --yes --skip-admin --skip-worker
 node ./bin/asaje.js doctor ../my-app
 node ./bin/asaje.js publish .
+node ./bin/asaje.js update ../my-app --dry-run
+node ./bin/asaje.js update ../my-app --include admin/src/stores/session.ts --yes
 node ./bin/asaje.js setup-railway ../my-app --yes
 node ./bin/asaje.js setup-railway ../my-app --yes --dry-run
 node ./bin/asaje.js sync-railway-env ../my-app --yes
+node ./bin/asaje.js destroy-railway ../my-app --scope environment --yes
 ```
 
 ## Publish checklist

package/bin/create-asaje-go-vue.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import crypto from "node:crypto";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import {
@@ -46,6 +47,20 @@ const RAILWAY_APP_SERVICE_SPECS = [
     serviceName: "realtime-gateway",
   },
 ];
+const SAFE_UPDATE_PATHS = [
+  "docker-compose.yml",
+  "admin/.env.example",
+  "admin/Dockerfile",
+  "admin/railway.json",
+  "admin/nginx",
+  "api/.env.example",
+  "api/Dockerfile",
+  "api/railway.json",
+  "api/docs",
+  "realtime-gateway/.env.example",
+  "realtime-gateway/Dockerfile",
+  "realtime-gateway/railway.json",
+];
 const ENV_FILE_SPECS = [
   { envPath: "admin/.env", examplePath: "admin/.env.example" },
   { envPath: "api/.env", examplePath: "api/.env.example" },
@@ -83,6 +98,12 @@ async function main() {
       return;
     }
 
+    if (invocation.command === "update") {
+      await runUpdate(invocation.argv);
+      outro(pc.green("Project update complete."));
+      return;
+    }
+
     if (invocation.command === "setup-railway") {
       await runSetupRailway(invocation.argv);
       outro(pc.green("Railway setup complete."));
@@ -95,6 +116,12 @@ async function main() {
       return;
     }
 
+    if (invocation.command === "destroy-railway") {
+      await runDestroyRailway(invocation.argv);
+      outro(pc.green("Railway teardown complete."));
+      return;
+    }
+
     await runCreate(invocation.argv);
     outro(pc.green("Project ready."));
   } catch (error) {
@@ -135,6 +162,10 @@ function resolveInvocation(argv) {
       return { argv: rawArgs.slice(1), command: "publish", title: "asaje publish" };
     }
 
+    if (firstArg === "update") {
+      return { argv: rawArgs.slice(1), command: "update", title: "asaje update" };
+    }
+
     if (firstArg === "setup-railway") {
       return { argv: rawArgs.slice(1), command: "setup-railway", title: "asaje setup-railway" };
     }
@@ -143,6 +174,10 @@ function resolveInvocation(argv) {
       return { argv: rawArgs.slice(1), command: "sync-railway-env", title: "asaje sync-railway-env" };
     }
 
+    if (firstArg === "destroy-railway") {
+      return { argv: rawArgs.slice(1), command: "destroy-railway", title: "asaje destroy-railway" };
+    }
+
     if (firstArg === "create") {
       return { argv: rawArgs.slice(1), command: "create", title: "asaje create" };
     }
@@ -162,6 +197,22 @@ function resolveInvocation(argv) {
     return { argv: rawArgs.slice(1), command: "publish", title: "create-asaje-go-vue" };
   }
 
+  if (firstArg === "update") {
+    return { argv: rawArgs.slice(1), command: "update", title: "create-asaje-go-vue" };
+  }
+
+  if (firstArg === "setup-railway") {
+    return { argv: rawArgs.slice(1), command: "setup-railway", title: "create-asaje-go-vue" };
+  }
+
+  if (firstArg === "sync-railway-env") {
+    return { argv: rawArgs.slice(1), command: "sync-railway-env", title: "create-asaje-go-vue" };
+  }
+
+  if (firstArg === "destroy-railway") {
+    return { argv: rawArgs.slice(1), command: "destroy-railway", title: "create-asaje-go-vue" };
+  }
+
   return { argv: rawArgs, command: "create", title: "create-asaje-go-vue" };
 }
 
@@ -172,16 +223,20 @@ function printHelp() {
   console.log(`- ${pc.bold("asaje start [directory]")} start a configured project`);
   console.log(`- ${pc.bold("asaje doctor [directory]")} check environment and project readiness`);
   console.log(`- ${pc.bold("asaje publish")} run npm publish checklist for the CLI package`);
+  console.log(`- ${pc.bold("asaje update [directory]")} update managed boilerplate files from the template`);
   console.log(`- ${pc.bold("asaje setup-railway [directory]")} provision Railway infrastructure for a project`);
   console.log(`- ${pc.bold("asaje sync-railway-env [directory]")} sync Railway app variables without provisioning`);
+  console.log(`- ${pc.bold("asaje destroy-railway [directory]")} delete the linked Railway environment or project`);
   console.log(pc.bold("\nExamples"));
   console.log(`- ${pc.bold("npx create-asaje-go-vue my-app")}`);
   console.log(`- ${pc.bold("node ./bin/create-asaje-go-vue.js my-app --yes")}`);
   console.log(`- ${pc.bold("node ./bin/asaje.js start ../my-app")}`);
   console.log(`- ${pc.bold("node ./bin/asaje.js doctor ..")}`);
   console.log(`- ${pc.bold("node ./bin/asaje.js publish")}`);
+  console.log(`- ${pc.bold("node ./bin/asaje.js update .. --dry-run")}`);
   console.log(`- ${pc.bold("node ./bin/asaje.js setup-railway ..")}`);
   console.log(`- ${pc.bold("node ./bin/asaje.js sync-railway-env ..")}`);
+  console.log(`- ${pc.bold("node ./bin/asaje.js destroy-railway ..")}`);
 }
 
 async function runCreate(argv) {
@@ -276,6 +331,71 @@ function parseCreateArgs(argv) {
   return { ...options, directory: positionals[0] };
 }
 
+function parseUpdateArgs(argv) {
+  const options = {
+    branch: undefined,
+    directory: ".",
+    dryRun: false,
+    include: [],
+    template: undefined,
+    yes: false,
+  };
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--yes" || arg === "-y") {
+      options.yes = true;
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg === "--template") {
+      options.template = argv[index + 1] || options.template;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--template=")) {
+      options.template = arg.split("=")[1] || options.template;
+      continue;
+    }
+
+    if (arg === "--branch") {
+      options.branch = argv[index + 1] || options.branch;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--branch=")) {
+      options.branch = arg.split("=")[1] || options.branch;
+      continue;
+    }
+
+    if (arg === "--include") {
+      options.include.push(...splitCommaSeparatedPaths(argv[index + 1] || ""));
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--include=")) {
+      options.include.push(...splitCommaSeparatedPaths(arg.split("=")[1] || ""));
+      continue;
+    }
+
+    positionals.push(arg);
+  }
+
+  options.directory = positionals[0] || options.directory;
+  options.include = uniquePaths(options.include);
+  return options;
+}
+
 async function collectCreateAnswers(args) {
   const defaultDirectory = args.directory || "my-asaje-app";
   const defaultSlug = slugify(path.basename(defaultDirectory));
@@ -610,6 +730,44 @@ async function collectCreateAnswers(args) {
   });
 }
 
+async function collectUpdateAnswers(args) {
+  if (args.yes) {
+    return args;
+  }
+
+  const directory = await prompt(
+    text({
+      defaultValue: args.directory,
+      message: "Project directory to update?",
+      placeholder: ".",
+      validate(value) {
+        return value.trim().length === 0 ? "Project directory is required" : undefined;
+      },
+    }),
+  );
+
+  const include = args.include.length
+    ? args.include
+    : splitCommaSeparatedPaths(
+        await prompt(
+          text({
+            defaultValue: "",
+            message: "Additional files or directories to overwrite from the template? (optional, comma-separated)",
+            placeholder: "admin/src/stores/session.ts,admin/src/services/http/session.ts",
+          }),
+        ),
+      );
+
+  return {
+    branch: args.branch,
+    directory,
+    dryRun: args.dryRun,
+    include,
+    template: args.template,
+    yes: true,
+  };
+}
+
 function buildCreateAnswers(input) {
   const directory = input.directory.trim();
   const slug = slugify(path.basename(directory));
@@ -911,6 +1069,48 @@ async function runPublish(argv) {
   console.log(`- Publish with ${pc.bold("npm publish")}`);
 }
 
+async function runUpdate(argv) {
+  const args = parseUpdateArgs(argv);
+  const answers = await collectUpdateAnswers(args);
+  const projectDir = path.resolve(process.cwd(), answers.directory);
+
+  await ensureProjectStructure(projectDir);
+
+  const projectConfig = await loadProjectConfig(projectDir);
+  const templateRepository = answers.template || projectConfig?.template?.repository || DEFAULT_TEMPLATE;
+  const templateBranch = answers.branch || projectConfig?.template?.branch || DEFAULT_BRANCH;
+  const templateDir = await fs.mkdtemp(path.join(os.tmpdir(), "asaje-update-"));
+
+  try {
+    console.log(pc.dim(`\nCloning template ${templateRepository}#${templateBranch}...`));
+    await cloneTemplate(templateRepository, templateBranch, templateDir);
+    await cleanupTemplateFiles(templateDir);
+
+    const selectedPaths = uniquePaths([...SAFE_UPDATE_PATHS, ...answers.include]);
+    const summary = await applyTemplateUpdates({
+      dryRun: answers.dryRun,
+      projectDir,
+      selectedPaths,
+      templateDir,
+    });
+
+    if (!answers.dryRun) {
+      await updateProjectTemplateConfig(projectDir, projectConfig, templateRepository, templateBranch);
+    }
+
+    printUpdateSummary({
+      branch: templateBranch,
+      dryRun: answers.dryRun,
+      include: answers.include,
+      projectDir,
+      repository: templateRepository,
+      summary,
+    });
+  } finally {
+    await fs.remove(templateDir);
+  }
+}
+
 async function runSetupRailway(argv) {
   const args = parseSetupRailwayArgs(argv);
   const answers = await collectSetupRailwayAnswers(args);
@@ -1098,6 +1298,67 @@ async function runSyncRailwayEnv(argv) {
   });
 }
 
+async function runDestroyRailway(argv) {
+  const args = parseDestroyRailwayArgs(argv);
+  const answers = await collectDestroyRailwayAnswers(args);
+  const projectDir = path.resolve(process.cwd(), answers.directory);
+
+  await ensureProjectStructure(projectDir);
+  await ensureRailwayCliInstalled();
+  await ensureRailwayAuthenticated(projectDir, answers.environment);
+
+  const railwayContext = await loadRailwayContext(projectDir, answers.environment);
+  const targetEnvironment = answers.environment || railwayContext.environmentId || railwayContext.environmentName;
+  const targetProject = railwayContext.projectId || railwayContext.projectName;
+
+  if (answers.scope === "project") {
+    if (!targetProject) {
+      throw new Error(`Unable to determine Railway project for ${projectDir}. Link the directory first with \`railway link\`.`);
+    }
+
+    console.log(pc.bold("\nDestroy Railway project"));
+    console.log(`- Project: ${pc.bold(railwayContext.projectName || railwayContext.projectId)}`);
+    if (answers.dryRun) {
+      console.log(`- Dry run: would delete project ${pc.bold(targetProject)}`);
+      return;
+    }
+
+    const commandArgs = ["project", "delete", "--project", targetProject, "--yes"];
+    if (answers.twoFactorCode) {
+      commandArgs.push("--2fa-code", answers.twoFactorCode);
+    }
+    await runRailwayCommand(projectDir, undefined, commandArgs);
+  } else {
+    if (!targetEnvironment) {
+      throw new Error(`Unable to determine Railway environment for ${projectDir}. Pass \`--environment\` or link the directory first.`);
+    }
+
+    await ensureRailwayEnvironmentLinked(projectDir, targetEnvironment);
+
+    console.log(pc.bold("\nDestroy Railway environment"));
+    console.log(`- Environment: ${pc.bold(targetEnvironment)}`);
+    if (railwayContext.projectName || railwayContext.projectId) {
+      console.log(`- Project: ${pc.bold(railwayContext.projectName || railwayContext.projectId)}`);
+    }
+    if (answers.dryRun) {
+      console.log(`- Dry run: would delete environment ${pc.bold(targetEnvironment)}`);
+      return;
+    }
+
+    const commandArgs = ["environment", "delete", targetEnvironment, "--yes"];
+    if (answers.twoFactorCode) {
+      commandArgs.push("--2fa-code", answers.twoFactorCode);
+    }
+    await runRailwayCommand(projectDir, undefined, commandArgs);
+  }
+
+  const manifestPath = path.join(projectDir, RAILWAY_MANIFEST_FILENAME);
+  if (await fs.pathExists(manifestPath)) {
+    await fs.remove(manifestPath);
+    console.log(`- Removed local ${pc.bold(RAILWAY_MANIFEST_FILENAME)} manifest`);
+  }
+}
+
 function parseDirectoryArgs(argv) {
   return { directory: argv[0] || "." };
 }
@@ -1154,6 +1415,74 @@ function parseSetupRailwayArgs(argv) {
   return options;
 }
 
+function parseDestroyRailwayArgs(argv) {
+  const options = {
+    directory: ".",
+    dryRun: false,
+    environment: undefined,
+    scope: "environment",
+    twoFactorCode: undefined,
+    yes: false,
+  };
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--yes" || arg === "-y") {
+      options.yes = true;
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg === "--environment" || arg === "-e") {
+      options.environment = argv[index + 1] || options.environment;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--environment=")) {
+      options.environment = arg.split("=")[1] || options.environment;
+      continue;
+    }
+
+    if (arg === "--scope") {
+      options.scope = argv[index + 1] || options.scope;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--scope=")) {
+      options.scope = arg.split("=")[1] || options.scope;
+      continue;
+    }
+
+    if (arg === "--2fa-code") {
+      options.twoFactorCode = argv[index + 1] || options.twoFactorCode;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--2fa-code=")) {
+      options.twoFactorCode = arg.split("=")[1] || options.twoFactorCode;
+      continue;
+    }
+
+    positionals.push(arg);
+  }
+
+  options.directory = positionals[0] || options.directory;
+  if (!["environment", "project"].includes(options.scope)) {
+    throw new Error("--scope must be either 'environment' or 'project'");
+  }
+
+  return options;
+}
+
 async function collectSetupRailwayAnswers(args) {
   if (args.yes) {
     return {
@@ -1207,6 +1536,68 @@ async function collectSetupRailwayAnswers(args) {
   };
 }
 
+async function collectDestroyRailwayAnswers(args) {
+  if (args.yes) {
+    return args;
+  }
+
+  const directory = await prompt(
+    text({
+      defaultValue: args.directory,
+      message: "Project directory linked to Railway?",
+      placeholder: ".",
+      validate(value) {
+        return value.trim().length === 0 ? "Project directory is required" : undefined;
+      },
+    }),
+  );
+
+  const scope = await prompt(
+    select({
+      initialValue: args.scope,
+      message: "What should be deleted?",
+      options: [
+        { label: "Environment", value: "environment", hint: "Delete one Railway environment and its services/resources" },
+        { label: "Project", value: "project", hint: "Delete the whole Railway project" },
+      ],
+    }),
+  );
+
+  let environment = args.environment;
+  if (scope === "environment" && !environment) {
+    environment = await prompt(
+      text({
+        defaultValue: "",
+        message: "Railway environment name or ID? (leave empty for linked default)",
+        placeholder: "production",
+      }),
+    );
+  }
+
+  const confirmed = await prompt(
+    confirm({
+      initialValue: false,
+      message:
+        scope === "project"
+          ? "Delete the whole Railway project and all its environments?"
+          : `Delete the Railway environment${environment ? ` ${environment}` : ""} and all its services/resources?`,
+    }),
+  );
+
+  if (!confirmed) {
+    throw new Error("Railway teardown cancelled.");
+  }
+
+  return {
+    directory,
+    dryRun: args.dryRun,
+    environment: environment?.trim() || undefined,
+    scope,
+    twoFactorCode: args.twoFactorCode,
+    yes: true,
+  };
+}
+
 async function ensureRailwayCliInstalled() {
   const result = await checkCommand({ command: "railway", args: ["--version"], name: "railway" });
   if (!result.ok) {
@@ -1504,6 +1895,8 @@ async function ensureRailwayAppService(config) {
       config.serviceName,
       "--image",
       config.seedImage || "alpine:3.22",
+      "--variables",
+      `ASAJE_BOOTSTRAP_SERVICE=${config.serviceName}`,
     ]);
   }
 
@@ -2399,6 +2792,115 @@ async function ensureProjectStructure(projectDir) {
   }
 }
 
+async function loadProjectConfig(projectDir) {
+  const configPath = path.join(projectDir, "asaje.config.json");
+  if (!(await fs.pathExists(configPath))) {
+    return null;
+  }
+
+  return fs.readJson(configPath);
+}
+
+async function updateProjectTemplateConfig(projectDir, projectConfig, templateRepository, templateBranch) {
+  const configPath = path.join(projectDir, "asaje.config.json");
+  const nextConfig = {
+    ...(projectConfig || {}),
+    template: {
+      branch: templateBranch,
+      repository: templateRepository,
+    },
+  };
+
+  await fs.writeJson(configPath, nextConfig, { spaces: 2 });
+}
+
+async function applyTemplateUpdates(config) {
+  const summary = {
+    missing: [],
+    skipped: [],
+    updated: [],
+  };
+
+  for (const relativePath of config.selectedPaths) {
+    const sourcePath = path.join(config.templateDir, relativePath);
+    const destinationPath = path.join(config.projectDir, relativePath);
+
+    if (!(await fs.pathExists(sourcePath))) {
+      summary.missing.push(relativePath);
+      continue;
+    }
+
+    const sourceStats = await fs.stat(sourcePath);
+    if (config.dryRun) {
+      summary.updated.push(relativePath);
+      continue;
+    }
+
+    if (sourceStats.isDirectory()) {
+      await fs.remove(destinationPath);
+      await fs.copy(sourcePath, destinationPath);
+    } else {
+      await fs.ensureDir(path.dirname(destinationPath));
+      await fs.copyFile(sourcePath, destinationPath);
+    }
+
+    summary.updated.push(relativePath);
+  }
+
+  summary.skipped = config.selectedPaths.filter((relativePath) => !summary.updated.includes(relativePath) && !summary.missing.includes(relativePath));
+  return summary;
+}
+
+function printUpdateSummary(config) {
+  console.log(pc.bold("\nUpdate"));
+  console.log(`- Directory: ${pc.bold(config.projectDir)}`);
+  console.log(`- Template: ${pc.bold(`${config.repository}#${config.branch}`)}`);
+  console.log(`- Safe paths: ${pc.bold(String(SAFE_UPDATE_PATHS.length))}`);
+  if (config.include.length > 0) {
+    console.log(`- Extra include: ${pc.bold(config.include.join(", "))}`);
+  }
+
+  console.log(pc.bold("\nUpdated"));
+  if (config.summary.updated.length === 0) {
+    console.log("- No files selected for update");
+  } else {
+    for (const relativePath of config.summary.updated) {
+      console.log(`- ${config.dryRun ? "would update" : "updated"} ${pc.bold(relativePath)}`);
+    }
+  }
+
+  if (config.summary.missing.length > 0) {
+    console.log(pc.bold("\nMissing In Template"));
+    for (const relativePath of config.summary.missing) {
+      console.log(`- ${pc.bold(relativePath)}`);
+    }
+  }
+
+  if (config.dryRun) {
+    console.log("- Dry run only, local files were not modified");
+  }
+}
+
+function splitCommaSeparatedPaths(value) {
+  return value
+    .split(",")
+    .map((entry) => normalizeRelativePath(entry))
+    .filter(Boolean);
+}
+
+function uniquePaths(paths) {
+  return [...new Set(paths.map((entry) => normalizeRelativePath(entry)).filter(Boolean))];
+}
+
+function normalizeRelativePath(value) {
+  const trimmed = String(value || "").trim();
+  if (!trimmed) {
+    return "";
+  }
+
+  return trimmed.replace(/^\.\//, "").replace(/\\/g, "/").replace(/\/$/, "");
+}
+
 async function ensureEnvFiles(projectDir) {
   for (const spec of ENV_FILE_SPECS) {
     const envPath = path.join(projectDir, spec.envPath);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-asaje-go-vue",
-	"version": "0.2.6",
+	"version": "0.2.8",
 	"description": "CLI to scaffold, configure, and run the Asaje Go + Vue boilerplate",
 	"type": "module",
 	"bin": {