@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/cli/commands/create.js

@@ -0,0 +1,250 @@
+import chalk from "chalk";
+import { execSync } from "child_process";
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Project-name validator (F17). Mirrors npm's package-name rules
+ * (the loose subset that travels safely in directory paths). Reject
+ * names that:
+ *   - contain path separators (`/`, `\`)
+ *   - contain `..` (parent-dir traversal, even if `path.resolve` would
+ *     later catch it)
+ *   - contain null bytes (filesystem string-termination footgun)
+ *   - start with `.` (hidden / dotfile collision)
+ *   - start with a digit (npm forbids; npm-compatible names start with
+ *     a letter)
+ *   - contain anything outside `[a-zA-Z0-9_-]`
+ *
+ * Rejecting up front avoids filesystem clobbering of user-owned paths
+ * via `ship-api create ../../../etc/foo` (the `path.resolve` call
+ * downstream resolves out of `cwd` without these checks).
+ */
+const PROJECT_NAME_RE = /^[a-z][a-z0-9_-]*$/i;
+const FORBIDDEN_CHARS = ["/", "\\", "\0", ".."];
+
+export function validateProjectName(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    return "must be a non-empty string";
+  }
+  for (const forbidden of FORBIDDEN_CHARS) {
+    if (name.includes(forbidden)) {
+      return `must not contain ${JSON.stringify(forbidden)}`;
+    }
+  }
+  if (!PROJECT_NAME_RE.test(name)) {
+    return "must match /^[a-z][a-z0-9_-]*$/i (npm-package-name rules: start with a letter, then letters / digits / `-` / `_`)";
+  }
+  return null;
+}
+
+export async function createProject(projectName, _options) {
+  const isCurrentDirectory = _options.currentDir;
+
+  // F17: name validation. Skipped when `--current-dir` because that
+  // path uses cwd, not the name, and is purely a display string then.
+  if (!isCurrentDirectory) {
+    const reason = validateProjectName(projectName);
+    if (reason) {
+      console.error(chalk.red(`✗ Invalid project name "${projectName}": ${reason}`));
+      process.exit(1);
+    }
+  }
+
+  const projectPath = isCurrentDirectory ? process.cwd() : path.resolve(process.cwd(), projectName);
+  const displayName = isCurrentDirectory ? "current directory" : projectName;
+
+  console.log(chalk.blue(`🚀 Creating ShipAPI project: ${projectName}`));
+  if (isCurrentDirectory) {
+    console.log(chalk.blue(`📁 Installing in current directory`));
+  }
+
+  // Check if directory already exists (only for new directories)
+  if (!isCurrentDirectory) {
+    try {
+      await fs.access(projectPath);
+      throw new Error(`Directory ${projectName} already exists`);
+    } catch (_error) {
+      if (_error.code !== "ENOENT") {
+        throw _error;
+      }
+    }
+
+    // Create project directory
+    await fs.mkdir(projectPath, { recursive: true });
+  }
+
+  // Copy template files
+  await copyTemplate(projectPath, _options.template);
+
+  // Process template placeholders
+  await processTemplateFiles(projectPath, projectName);
+
+  // Install dependencies
+  if (!_options.skipInstall) {
+    console.log(chalk.yellow("📦 Installing dependencies..."));
+    process.chdir(projectPath);
+    execSync("npm install", { stdio: "inherit" });
+  }
+
+  // Initialize git
+  if (!_options.skipGit) {
+    console.log(chalk.yellow("🔧 Initializing git repository..."));
+    try {
+      execSync("git init", { stdio: "inherit" });
+      execSync("git add .", { stdio: "inherit" });
+      execSync('git commit -m "Initial commit: ShipAPI project setup"', { stdio: "inherit" });
+    } catch (_error) {
+      console.log(chalk.yellow("⚠️  Git initialization failed, continuing..."));
+    }
+  }
+
+  console.log(chalk.green(`✅ Project "${projectName}" created successfully in ${displayName}!`));
+  console.log(chalk.cyan(`\nNext steps:`));
+  if (!isCurrentDirectory) {
+    console.log(chalk.cyan(`  cd ${projectName}`));
+  }
+  console.log(chalk.cyan(`  npx ship-api add accounts   # Add authentication module`));
+  console.log(chalk.cyan(`  npm run local`));
+  console.log(chalk.cyan(`\nDocumentation: https://github.com/SixthSummit/Ship`));
+}
+
+async function copyTemplate(projectPath, template) {
+  const templatePath = path.join(__dirname, "..", "..", "templates", template);
+
+  try {
+    await fs.access(templatePath);
+  } catch (_error) {
+    throw new Error(`Template '${template}' not found`);
+  }
+
+  await copyDirectory(templatePath, projectPath);
+}
+
+async function copyDirectory(src, dest) {
+  const entries = await fs.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    // npm strips .gitignore (and other dot-leading ignore files) during
+    // package publish — templates work around it by shipping
+    // `_gitignore` and renaming on scaffold. Same trick as
+    // `create-next-app` and friends. Generalized to `_<name>` → `.<name>`
+    // so future ignore-style files (`.npmignore`, `.dockerignore`, etc.)
+    // can use the same convention.
+    const destName = entry.name.startsWith("_") ? "." + entry.name.slice(1) : entry.name;
+    const destPath = path.join(dest, destName);
+
+    if (entry.isDirectory()) {
+      await fs.mkdir(destPath, { recursive: true });
+      await copyDirectory(srcPath, destPath);
+    } else {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+async function processTemplateFiles(projectPath, projectName) {
+  // Determine ship-api version to use
+  const shipApiVersion = await getShipApiVersion();
+  const observabilityVersion = await getBundledDependencyVersion(
+    "@sixthsummit/ship-observability-otel",
+    "observability-otel",
+  );
+  console.log(chalk.blue(`📦 Using @sixthsummit/ship-api version: ${shipApiVersion}`));
+
+  // Process package.json - parse as JSON and update fields
+  const packageJsonPath = path.join(projectPath, "package.json");
+  const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+
+  packageJson.name = projectName;
+
+  // Insert @sixthsummit/ship-api at the beginning of dependencies, with
+  // the version resolved by getShipApiVersion(). Templates SHOULD NOT
+  // declare @sixthsummit/ship-api themselves — but defensively strip it
+  // from existingDeps before the spread so the explicit version wins
+  // (otherwise the template's stale literal overrides via property-key
+  // collision).
+  const {
+    "@sixthsummit/ship-api": _existingShipApi,
+    "@sixthsummit/ship-observability-otel": _existingObservability,
+    ...existingDeps
+  } = packageJson.dependencies ?? {};
+  packageJson.dependencies = {
+    "@sixthsummit/ship-api": shipApiVersion,
+    "@sixthsummit/ship-observability-otel": observabilityVersion,
+    ...existingDeps,
+  };
+
+  await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+
+  // Process .env.example - update PROJECT_ROOT
+  const envExamplePath = path.join(projectPath, ".env.example");
+  try {
+    let envExample = await fs.readFile(envExamplePath, "utf8");
+    envExample = envExample.replace(/PROJECT_ROOT=.*/, `PROJECT_ROOT=${projectPath}`);
+    envExample = envExample.replace(
+      /DATABASE_URL=postgresql:\/\/username:password@localhost:5432\/.*/,
+      `DATABASE_URL=postgresql://username:password@localhost:5432/${projectName}`,
+    );
+    await fs.writeFile(envExamplePath, envExample);
+  } catch (_error) {
+    // .env.example might not exist, that's okay
+  }
+}
+
+async function getShipApiVersion() {
+  // Read ship-api's package.json to get current version
+  const shipApiPackageJsonPath = path.join(__dirname, "..", "..", "package.json");
+  const shipApiPackageJson = JSON.parse(await fs.readFile(shipApiPackageJsonPath, "utf8"));
+  const currentVersion = shipApiPackageJson.version;
+  const isPrerelease = currentVersion.includes("-"); // e.g., 3.0.0-beta.1
+
+  if (isPrerelease) {
+    // For prereleases (beta, rc), use caret range to allow updates to newer betas and stable
+    // ^3.0.0-beta.1 will match 3.0.0-beta.2, 3.0.0, 3.0.1, etc.
+    return `^${currentVersion}`;
+  }
+
+  // For stable releases, try to get the latest stable version from npm
+  try {
+    const latestVersion = execSync("npm view @sixthsummit/ship-api version", {
+      encoding: "utf8",
+    }).trim();
+    return `^${latestVersion}`;
+  } catch (_error) {
+    // If npm view fails, use current version
+    return `^${currentVersion}`;
+  }
+}
+
+/**
+ * Resolve a package split out of the monolith to the version declared by the
+ * installed CLI. Published package manifests contain a normal semver range;
+ * the workspace fallback keeps local scaffold tests deterministic.
+ */
+export async function getBundledDependencyVersion(packageName, workspaceDirectory) {
+  const shipApiPackageJsonPath = path.join(__dirname, "..", "..", "package.json");
+  const shipApiPackageJson = JSON.parse(await fs.readFile(shipApiPackageJsonPath, "utf8"));
+  const declared = shipApiPackageJson.dependencies?.[packageName];
+
+  if (typeof declared !== "string") {
+    throw new Error(`${packageName} is not declared by @sixthsummit/ship-api`);
+  }
+  if (!declared.startsWith("workspace:")) return declared;
+
+  const workspacePackageJsonPath = path.join(
+    __dirname,
+    "..",
+    "..",
+    "..",
+    workspaceDirectory,
+    "package.json",
+  );
+  const workspacePackageJson = JSON.parse(await fs.readFile(workspacePackageJsonPath, "utf8"));
+  return `^${workspacePackageJson.version}`;
+}

package/cli/commands/dev.js

@@ -0,0 +1,227 @@
+import chalk from "chalk";
+import { spawn } from "child_process";
+import fs from "fs/promises";
+import path from "path";
+
+/**
+ * `ship-api dev` — local-stack orchestrator.
+ *
+ * Brings up the dependency containers (Postgres, Redis, optional OTel
+ * collector) via Docker Compose, then runs the project's dev script with
+ * hot reload, then polls a health endpoint until it goes green and prints
+ * the URL — the "new project just works" experience.
+ *
+ *   --bare    Skip Docker. Use this when Postgres/Redis are already running
+ *             on the host (or you're shelling into a remote stack).
+ *   --reset   `docker compose down -v` before starting — drops volumes for
+ *             a clean slate (and forces fresh migrations on next boot).
+ *   --port    Override the polled port (defaults to 3000 / $PORT).
+ *
+ * Implementation notes:
+ *
+ *   • Compose file discovery: looks for `compose.yml`, `compose.yaml`,
+ *     `docker-compose.yml`, `docker-compose.yaml` in cwd. If none, behaves
+ *     as `--bare`.
+ *   • Service selection: spins up *only* dependency services (`postgres`,
+ *     `redis`, `jaeger`, `otel-collector`) — never the `api` service,
+ *     since the point of `dev` is to run the app via `tsx watch` for
+ *     hot reload. (`jaeger` is the v4 template's trace viewer; the
+ *     legacy `otel-collector` name is kept for v3 / older v4 templates
+ *     that haven't been updated.)
+ *   • Health probe: tries `/livez`, then `/healthz`, then `/health-check`,
+ *     then `/`. First non-5xx response wins. Polls every 500ms with a 60s
+ *     timeout.
+ *   • Signal handling: forwards SIGINT/SIGTERM to the npm child. Compose
+ *     stays running so the next `dev` invocation reuses warm containers
+ *     (use `--reset` to tear down explicitly).
+ */
+
+const DEPENDENCY_SERVICES = ["postgres", "redis", "jaeger", "otel-collector"];
+const HEALTH_PATHS = ["/livez", "/healthz", "/health-check", "/"];
+const HEALTH_TIMEOUT_MS = 60_000;
+const HEALTH_INTERVAL_MS = 500;
+
+export async function devCommand(options = {}) {
+  const cwd = process.cwd();
+  const port = Number(options.port ?? process.env.PORT ?? 3000);
+  const useDocker = !options.bare;
+  const reset = Boolean(options.reset);
+
+  console.log(chalk.blue("🚀 ship-api dev"));
+
+  let composeFile = null;
+  if (useDocker) {
+    composeFile = await findComposeFile(cwd);
+    if (!composeFile) {
+      console.log(
+        chalk.yellow(
+          "⚠ no docker-compose.yml found — running in --bare mode (assumes Postgres/Redis are already up)",
+        ),
+      );
+    }
+  }
+
+  if (composeFile && reset) {
+    console.log(chalk.gray(`↻ docker compose down -v (${composeFile})`));
+    await runToCompletion("docker", ["compose", "-f", composeFile, "down", "-v"], { cwd });
+  }
+
+  if (composeFile) {
+    const services = await selectExistingServices(composeFile, cwd, DEPENDENCY_SERVICES);
+    if (services.length === 0) {
+      console.log(
+        chalk.yellow(
+          `⚠ ${composeFile} has no services matching ${DEPENDENCY_SERVICES.join(", ")} — skipping compose up`,
+        ),
+      );
+    } else {
+      console.log(chalk.gray(`↑ docker compose up -d ${services.join(" ")}`));
+      const composeUp = await runToCompletion(
+        "docker",
+        ["compose", "-f", composeFile, "up", "-d", ...services],
+        { cwd },
+      );
+      if (composeUp.code !== 0) {
+        throw new Error(`docker compose up failed (exit ${composeUp.code})`);
+      }
+    }
+  }
+
+  // Pick the dev script. Templates expose `local` (v3) or `dev` (v4).
+  const devScript = await pickDevScript(cwd);
+  console.log(chalk.gray(`▶ npm run ${devScript}`));
+
+  const npmChild = spawn("npm", ["run", devScript], {
+    cwd,
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  let cleanedUp = false;
+  const cleanup = (signal) => {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    if (!npmChild.killed) npmChild.kill(signal);
+  };
+  process.on("SIGINT", () => cleanup("SIGINT"));
+  process.on("SIGTERM", () => cleanup("SIGTERM"));
+
+  const childExit = new Promise((resolve) => {
+    npmChild.once("exit", (code, signal) => resolve({ code, signal }));
+  });
+
+  // Race the health probe vs. an early child exit.
+  const healthResult = await Promise.race([
+    pollHealth(`http://localhost:${port}`),
+    childExit.then((r) => ({ kind: "child-exited", ...r })),
+  ]);
+
+  if (healthResult.kind === "child-exited") {
+    throw new Error(
+      `dev process exited before becoming healthy (code=${healthResult.code} signal=${healthResult.signal})`,
+    );
+  }
+  if (!healthResult.ok) {
+    console.log(
+      chalk.yellow(
+        `⚠ ${healthResult.reason}. The server may still be starting — try opening http://localhost:${port} in a moment.`,
+      ),
+    );
+  } else {
+    console.log(
+      chalk.green(
+        `✓ healthy at http://localhost:${port}${healthResult.path} — opening in your browser`,
+      ),
+    );
+  }
+
+  // Stay attached to the npm child so logs flow until Ctrl+C.
+  const { code } = await childExit;
+  if (code !== 0 && code !== null) {
+    process.exitCode = code;
+  }
+}
+
+// Exported for tests. Internal helpers used by `devCommand`.
+export const __test = {
+  findComposeFile: (...args) => findComposeFile(...args),
+  selectExistingServices: (...args) => selectExistingServices(...args),
+  pickDevScript: (...args) => pickDevScript(...args),
+};
+
+async function findComposeFile(cwd) {
+  const candidates = ["compose.yml", "compose.yaml", "docker-compose.yml", "docker-compose.yaml"];
+  for (const name of candidates) {
+    const full = path.join(cwd, name);
+    try {
+      await fs.access(full);
+      return name;
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+async function selectExistingServices(composeFile, cwd, candidates) {
+  // Cheap parse — read the file and look for top-level service keys via
+  // the indent-aware regex `\n  <name>:`. Avoids a YAML dep for a CLI tool.
+  const text = await fs.readFile(path.join(cwd, composeFile), "utf8");
+  const out = [];
+  for (const name of candidates) {
+    const re = new RegExp(`(?:^|\\n)  ${escapeRegex(name)}:`, "m");
+    if (re.test(text)) out.push(name);
+  }
+  return out;
+}
+
+async function pickDevScript(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  try {
+    const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+    const scripts = pkg.scripts ?? {};
+    if (scripts.dev) return "dev";
+    if (scripts.local) return "local";
+    if (scripts.start) return "start";
+  } catch {
+    // fall through
+  }
+  return "local";
+}
+
+async function pollHealth(baseUrl) {
+  const deadline = Date.now() + HEALTH_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    for (const p of HEALTH_PATHS) {
+      try {
+        const res = await fetch(`${baseUrl}${p}`, {
+          // Treat any 2xx/3xx/4xx as "the server is reachable enough".
+          // 5xx (or no response) keeps polling.
+        });
+        if (res.status < 500) {
+          return { kind: "healthy", ok: true, path: p, status: res.status };
+        }
+      } catch {
+        // connection refused / DNS / network — still booting
+      }
+    }
+    await new Promise((r) => setTimeout(r, HEALTH_INTERVAL_MS));
+  }
+  return {
+    kind: "healthy",
+    ok: false,
+    reason: `no health endpoint became reachable within ${HEALTH_TIMEOUT_MS / 1000}s`,
+  };
+}
+
+function runToCompletion(command, args, opts) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { ...opts, stdio: "inherit" });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve({ code, signal }));
+  });
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}