capstart 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrien Villermois
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# Capstart CLI
+
+Add Capacitor to an existing Next.js or TanStack Start application.
+
+```bash
+npx capstart init ..
+```
+
+Capstart detects the framework and package manager, configures a static or SPA
+build, installs Capacitor, adds native projects, builds the web application, and
+runs `cap sync`.
+
+Installation, build, and Capacitor command output is hidden by default. Capstart
+shows a single setup progress line and only prints a short command summary when
+something fails.
+
+Each main installation operation has its own step:
+
+```text
+◇ Configure Next.js
+◇ Configure Capacitor
+◇ Install Capacitor packages
+◇ Build the web app
+◇ Prepare iOS and Android projects
+◇ Synchronize native projects
+```
+
+The commands executed inside each step remain hidden.
+
+The detected framework is always shown and must be confirmed before Capstart
+changes the project:
+
+```text
+✓ Detected Next.js
+? Use the detected framework Next.js? Yes
+```
+
+If the detection is refused, Capstart lets you choose between Next.js and
+TanStack Start.
+
+## Supported frameworks
+
+- Next.js projects that can use static export
+- TanStack Start projects that can use SPA mode
+
+Server-only features must remain hosted remotely and be called from the mobile
+application over HTTP.
+
+## Usage
+
+```bash
+npx capstart init [directory] [options]
+```
+
+Examples:
+
+```bash
+npx capstart init .
+npx capstart init ../my-app --app-id com.example.myapp
+npx capstart init . --platforms ios
+npx capstart init . --framework tanstack-start --dry-run
+npx capstart init . --yes
+```
+
+Useful options:
+
+```text
+--framework <nextjs|tanstack-start>
+--app-id <id>
+--app-name <name>
+--platforms <ios,android>
+--skip-install
+--skip-build
+--skip-native
+--dry-run
+--yes
+```
+
+Use `--yes` to accept a single automatically detected framework in CI or other
+non-interactive environments. Use `--framework` to bypass detection
+confirmation and select an adapter explicitly.
+
+After a successful interactive initialization, Capstart detects whether GitHub
+CLI is installed and optionally proposes starring
+[AdrienADV/capstart](https://github.com/AdrienADV/capstart). The repository is
+only starred after explicit confirmation, and this step never runs in CI.
+
+The final output includes:
+
+- the scripts added to `package.json` and a short explanation of each one;
+- recommended Capacitor packages and production guidance at
+  [capstart.dev/docs/installation/#3-add-recommended-capacitor-base-plugins](https://capstart.dev/docs/installation/#3-add-recommended-capacitor-base-plugins);
+- an `Important` section explaining which framework server features must remain
+  remotely hosted.
+
+Example:
+
+```text
+Ready
+✓ Your base Capacitor setup is ready.
+
+Scripts added
+  npm run cap:sync
+    Build the web app and sync the native projects.
+  npm run cap:ios
+    Build, sync, and open the iOS project in Xcode.
+  npm run cap:android
+    Build, sync, and open the Android project in Android Studio.
+
+Next steps
+• Review recommended plugins, native configuration, and production setup:
+  https://capstart.dev/docs/installation/#3-add-recommended-capacitor-base-plugins
+
+Important
+! Next.js request-time features do not run inside the Capacitor app.
+  • Replace request-time Server Components and Server Actions with client-side
+    calls to API endpoints.
+  • Deploy those APIs, API routes, middleware, ISR, and other request-time logic
+    on a remote backend.
+  • Configure the mobile app with an HTTPS API base URL that is reachable from
+    the device.
+  • Do not use "localhost" for the backend URL: on a phone or emulator, it
+    points to the device itself.
+```
+
+After initialization:
+
+```bash
+npm run cap:sync
+npm run cap:ios
+npm run cap:android
+```
+
+The exact package-manager prefix is generated for npm, pnpm, Yarn, or Bun.
+
+## Development
+
+```bash
+cd cli
+npm install
+npm run typecheck
+npm test
+npm run build
+node dist/cli.js --help
+```

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,957 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command, InvalidArgumentError } from "commander";
+
+// src/adapters/nextjs.ts
+import { writeFile as writeFile2 } from "fs/promises";
+import path3 from "path";
+
+// src/core/ast.ts
+import path2 from "path";
+import {
+  Node,
+  Project,
+  SyntaxKind
+} from "ts-morph";
+
+// src/core/project.ts
+import { access, readFile, writeFile } from "fs/promises";
+import path from "path";
+var lockfiles = [
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"]
+];
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function loadProject(directory) {
+  const root = path.resolve(directory);
+  const packageJsonPath = path.join(root, "package.json");
+  if (!await pathExists(packageJsonPath)) {
+    throw new Error(`No package.json found in ${root}`);
+  }
+  const packageJson = JSON.parse(
+    await readFile(packageJsonPath, "utf8")
+  );
+  return {
+    root,
+    packageJsonPath,
+    packageJson,
+    packageManager: await detectPackageManager(root, packageJson)
+  };
+}
+async function savePackageJson(project, dryRun) {
+  if (dryRun) {
+    return;
+  }
+  await writeFile(
+    project.packageJsonPath,
+    `${JSON.stringify(project.packageJson, null, 2)}
+`
+  );
+}
+function hasDependency(project, dependency) {
+  return Boolean(
+    project.packageJson.dependencies?.[dependency] ?? project.packageJson.devDependencies?.[dependency]
+  );
+}
+function getProjectName(project) {
+  const rawName = project.packageJson.name ?? path.basename(project.root);
+  return rawName.replace(/^@[^/]+\//, "");
+}
+function createDefaultAppId(project) {
+  const slug = getProjectName(project).toLowerCase().replace(/[^a-z0-9]+/g, "").replace(/^[^a-z]+/, "");
+  return `com.capstart.${slug || "app"}`;
+}
+async function detectPackageManager(root, packageJson) {
+  for (const [lockfile, packageManager] of lockfiles) {
+    if (await pathExists(path.join(root, lockfile))) {
+      return packageManager;
+    }
+  }
+  if (typeof packageJson.packageManager === "string") {
+    const packageManager = packageJson.packageManager.split("@")[0];
+    if (packageManager === "npm" || packageManager === "pnpm" || packageManager === "yarn" || packageManager === "bun") {
+      return packageManager;
+    }
+  }
+  return "npm";
+}
+
+// src/core/ast.ts
+async function findConfigFile(root, names) {
+  for (const name of names) {
+    const filePath = path2.join(root, name);
+    if (await pathExists(filePath)) {
+      return filePath;
+    }
+  }
+  return void 0;
+}
+function loadSourceFile(filePath) {
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true
+  });
+  return project.addSourceFileAtPath(filePath);
+}
+function findExportedObject(sourceFile) {
+  for (const exportAssignment of sourceFile.getExportAssignments()) {
+    const expression = exportAssignment.getExpression();
+    const object = resolveObjectExpression(expression);
+    if (object) {
+      return object;
+    }
+  }
+  for (const binary of sourceFile.getDescendantsOfKind(
+    SyntaxKind.BinaryExpression
+  )) {
+    if (binary.getLeft().getText() === "module.exports") {
+      const object = resolveObjectExpression(binary.getRight());
+      if (object) {
+        return object;
+      }
+    }
+  }
+  return void 0;
+}
+function setObjectProperty(object, name, initializer) {
+  const property = object.getProperty(name);
+  if (!property) {
+    object.addPropertyAssignment({ name, initializer });
+    return;
+  }
+  if (Node.isPropertyAssignment(property)) {
+    property.setInitializer(initializer);
+    return;
+  }
+  throw new Error(`Cannot safely update the "${name}" configuration property.`);
+}
+function getOrCreateNestedObject(object, name) {
+  const property = object.getProperty(name);
+  if (!property) {
+    const created = object.addPropertyAssignment({
+      name,
+      initializer: "{}"
+    });
+    const initializer = created.getInitializer();
+    if (!Node.isObjectLiteralExpression(initializer)) {
+      throw new Error(`Could not create the "${name}" configuration property.`);
+    }
+    return initializer;
+  }
+  if (Node.isPropertyAssignment(property)) {
+    const initializer = property.getInitializer();
+    if (Node.isObjectLiteralExpression(initializer)) {
+      return initializer;
+    }
+  }
+  throw new Error(`Cannot safely merge the "${name}" configuration property.`);
+}
+function resolveObjectExpression(expression) {
+  if (Node.isObjectLiteralExpression(expression)) {
+    return expression;
+  }
+  if (Node.isIdentifier(expression)) {
+    const declaration = expression.getDefinitions()[0]?.getDeclarationNode();
+    if (Node.isVariableDeclaration(declaration)) {
+      const initializer = declaration.getInitializer();
+      if (Node.isObjectLiteralExpression(initializer)) {
+        return initializer;
+      }
+    }
+  }
+  return void 0;
+}
+
+// src/adapters/nextjs.ts
+var configNames = [
+  "next.config.ts",
+  "next.config.mts",
+  "next.config.mjs",
+  "next.config.js",
+  "next.config.cjs"
+];
+var nextjsAdapter = {
+  id: "nextjs",
+  label: "Next.js",
+  webDir: "out",
+  detect(project) {
+    return hasDependency(project, "next");
+  },
+  async validate(project) {
+    const diagnostics = [];
+    if (!project.packageJson.scripts?.build) {
+      diagnostics.push({
+        level: "error",
+        message: 'Missing a "build" script in package.json.'
+      });
+    }
+    const configPath = await findConfigFile(project.root, configNames);
+    if (configPath) {
+      const sourceFile = loadSourceFile(configPath);
+      if (!findExportedObject(sourceFile)) {
+        diagnostics.push({
+          level: "error",
+          message: "The existing Next.js config is too dynamic to update safely. Export a config object before running Capstart."
+        });
+      }
+    }
+    return diagnostics;
+  },
+  async configure(project, dryRun) {
+    const disclaimers = [
+      {
+        title: "Next.js request-time features do not run inside the Capacitor app.",
+        details: [
+          "Replace request-time Server Components and Server Actions with client-side calls to API endpoints.",
+          "Deploy those APIs, API routes, middleware, ISR, and other request-time logic on a remote backend.",
+          "Configure the mobile app with an HTTPS API base URL that is reachable from the device.",
+          'Do not use "localhost" for the backend URL: on a phone or emulator, it points to the device itself.'
+        ]
+      }
+    ];
+    const configPath = await findConfigFile(project.root, configNames);
+    if (!configPath) {
+      const newConfigPath = path3.join(project.root, "next.config.mjs");
+      if (!dryRun) {
+        await writeFile2(
+          newConfigPath,
+          [
+            "/** @type {import('next').NextConfig} */",
+            "const nextConfig = {",
+            '  output: "export",',
+            "  trailingSlash: true,",
+            "  images: {",
+            "    unoptimized: true,",
+            "  },",
+            "};",
+            "",
+            "export default nextConfig;",
+            ""
+          ].join("\n")
+        );
+      }
+      return { disclaimers };
+    }
+    const sourceFile = loadSourceFile(configPath);
+    const config = findExportedObject(sourceFile);
+    if (!config) {
+      throw new Error("Could not safely update the existing Next.js config.");
+    }
+    setObjectProperty(config, "output", '"export"');
+    setObjectProperty(config, "trailingSlash", "true");
+    const images = getOrCreateNestedObject(config, "images");
+    setObjectProperty(images, "unoptimized", "true");
+    if (!dryRun) {
+      await sourceFile.save();
+    }
+    return { disclaimers };
+  }
+};
+
+// src/adapters/tanstack-start.ts
+import { Node as Node2, SyntaxKind as SyntaxKind2 } from "ts-morph";
+var configNames2 = [
+  "vite.config.ts",
+  "vite.config.mts",
+  "vite.config.mjs",
+  "vite.config.js"
+];
+var tanstackStartAdapter = {
+  id: "tanstack-start",
+  label: "TanStack Start",
+  webDir: "dist/client",
+  detect(project) {
+    return hasDependency(project, "@tanstack/react-start");
+  },
+  async validate(project) {
+    const diagnostics = [];
+    if (!project.packageJson.scripts?.build) {
+      diagnostics.push({
+        level: "error",
+        message: 'Missing a "build" script in package.json.'
+      });
+    }
+    const configPath = await findConfigFile(project.root, configNames2);
+    if (!configPath) {
+      diagnostics.push({
+        level: "error",
+        message: "Could not find a Vite configuration file."
+      });
+      return diagnostics;
+    }
+    const call = findTanstackStartCall(configPath);
+    if (!call) {
+      diagnostics.push({
+        level: "error",
+        message: "Could not find tanstackStart() in the Vite configuration file."
+      });
+    }
+    return diagnostics;
+  },
+  async configure(project, dryRun) {
+    const configPath = await findConfigFile(project.root, configNames2);
+    if (!configPath) {
+      throw new Error("Could not find a Vite configuration file.");
+    }
+    const sourceFile = loadSourceFile(configPath);
+    const call = sourceFile.getDescendantsOfKind(SyntaxKind2.CallExpression).find(
+      (candidate) => candidate.getExpression().getText() === "tanstackStart"
+    );
+    if (!call) {
+      throw new Error("Could not find tanstackStart() in the Vite config.");
+    }
+    let options = call.getArguments()[0];
+    if (!options) {
+      call.addArgument("{}");
+      options = call.getArguments()[0];
+    }
+    if (!Node2.isObjectLiteralExpression(options)) {
+      throw new Error(
+        "Cannot safely update tanstackStart() because its options are not an object literal."
+      );
+    }
+    const spa = getOrCreateNestedObject(options, "spa");
+    setObjectProperty(spa, "enabled", "true");
+    const prerender = getOrCreateNestedObject(spa, "prerender");
+    setObjectProperty(prerender, "outputPath", '"/index.html"');
+    if (!dryRun) {
+      await sourceFile.save();
+    }
+    return {
+      disclaimers: [
+        {
+          title: "TanStack Start server features do not run inside the Capacitor app.",
+          details: [
+            "Move server functions and server routes to a deployed backend.",
+            "Configure the mobile app to call an HTTPS API URL that is reachable from the device.",
+            'Do not use "localhost" for the backend URL: on a phone or emulator, it points to the device itself.'
+          ]
+        }
+      ]
+    };
+  }
+};
+function findTanstackStartCall(configPath) {
+  return loadSourceFile(configPath).getDescendantsOfKind(SyntaxKind2.CallExpression).find((candidate) => candidate.getExpression().getText() === "tanstackStart");
+}
+
+// src/adapters/index.ts
+var adapters = [nextjsAdapter, tanstackStartAdapter];
+function getAdapter(id) {
+  const adapter = adapters.find((candidate) => candidate.id === id);
+  if (!adapter) {
+    throw new Error(`Unsupported framework: ${id}`);
+  }
+  return adapter;
+}
+function getAdapters() {
+  return adapters;
+}
+function detectAdapters(project) {
+  return adapters.filter((adapter) => adapter.detect(project));
+}
+
+// src/capacitor/configure.ts
+import { readFile as readFile2, writeFile as writeFile3 } from "fs/promises";
+import path4 from "path";
+
+// src/core/process.ts
+import { spawn } from "child_process";
+var maxErrorLines = 12;
+var maxCapturedOutput = 64e3;
+async function runCommand(command, args, cwd) {
+  await new Promise((resolve, reject) => {
+    let output = "";
+    const child = spawn(command, args, {
+      cwd,
+      shell: process.platform === "win32",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    child.on("error", reject);
+    child.stdout?.on("data", (chunk) => {
+      output = appendOutput(output, chunk.toString());
+    });
+    child.stderr?.on("data", (chunk) => {
+      output = appendOutput(output, chunk.toString());
+    });
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(
+        new Error(
+          [
+            `Command failed: ${command} ${args.join(" ")}`,
+            getErrorSummary(output)
+          ].filter(Boolean).join("\n")
+        )
+      );
+    });
+  });
+}
+function appendOutput(current, chunk) {
+  return `${current}${chunk}`.slice(-maxCapturedOutput);
+}
+function getErrorSummary(output) {
+  return output.replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, "").split(/[\r\n]+/).map((line) => line.trim().slice(0, 300)).filter(Boolean).slice(-maxErrorLines).join("\n");
+}
+async function commandExists(command, args = ["--version"]) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      shell: process.platform === "win32",
+      stdio: "ignore"
+    });
+    child.on("error", () => resolve(false));
+    child.on("exit", (code) => resolve(code === 0));
+  });
+}
+function installCommand(packageManager, packages, dev) {
+  const devFlag = dev ? ["-D"] : [];
+  switch (packageManager) {
+    case "bun":
+      return ["bun", ["add", ...devFlag, ...packages]];
+    case "pnpm":
+      return ["pnpm", ["add", ...devFlag, ...packages]];
+    case "yarn":
+      return ["yarn", ["add", ...devFlag, ...packages]];
+    case "npm":
+      return ["npm", ["install", ...dev ? ["--save-dev"] : [], ...packages]];
+  }
+}
+function runScriptCommand(packageManager, script) {
+  switch (packageManager) {
+    case "yarn":
+      return ["yarn", [script]];
+    case "bun":
+      return ["bun", ["run", script]];
+    case "pnpm":
+      return ["pnpm", ["run", script]];
+    case "npm":
+      return ["npm", ["run", script]];
+  }
+}
+function capacitorCommand(packageManager, args) {
+  switch (packageManager) {
+    case "bun":
+      return ["bunx", ["cap", ...args]];
+    case "pnpm":
+      return ["pnpm", ["exec", "cap", ...args]];
+    case "yarn":
+      return ["yarn", ["cap", ...args]];
+    case "npm":
+      return ["npm", ["exec", "cap", "--", ...args]];
+  }
+}
+function packageScriptPrefix(packageManager) {
+  switch (packageManager) {
+    case "yarn":
+      return "yarn";
+    case "bun":
+      return "bun run";
+    case "pnpm":
+      return "pnpm run";
+    case "npm":
+      return "npm run";
+  }
+}
+function capacitorScriptPrefix(packageManager) {
+  switch (packageManager) {
+    case "bun":
+      return "bunx cap";
+    case "pnpm":
+      return "pnpm exec cap";
+    case "yarn":
+      return "yarn cap";
+    case "npm":
+      return "npm exec cap --";
+  }
+}
+
+// src/capacitor/configure.ts
+var configNames3 = [
+  "capacitor.config.ts",
+  "capacitor.config.mts",
+  "capacitor.config.js",
+  "capacitor.config.mjs",
+  "capacitor.config.json"
+];
+async function configureCapacitor(project, options) {
+  const configPath = await findConfigFile(project.root, configNames3);
+  if (!configPath) {
+    if (!options.dryRun) {
+      await writeFile3(
+        path4.join(project.root, "capacitor.config.ts"),
+        [
+          'import type { CapacitorConfig } from "@capacitor/cli";',
+          "",
+          "const config: CapacitorConfig = {",
+          `  appId: ${JSON.stringify(options.appId)},`,
+          `  appName: ${JSON.stringify(options.appName)},`,
+          `  webDir: ${JSON.stringify(options.webDir)},`,
+          "};",
+          "",
+          "export default config;",
+          ""
+        ].join("\n")
+      );
+    }
+  } else if (configPath.endsWith(".json")) {
+    const config = JSON.parse(await readFile2(configPath, "utf8"));
+    config.webDir = options.webDir;
+    if (!options.dryRun) {
+      await writeFile3(configPath, `${JSON.stringify(config, null, 2)}
+`);
+    }
+  } else {
+    const sourceFile = loadSourceFile(configPath);
+    const config = findExportedObject(sourceFile);
+    if (!config) {
+      throw new Error(
+        `Cannot safely update the existing ${path4.basename(configPath)}.`
+      );
+    }
+    setObjectProperty(config, "webDir", JSON.stringify(options.webDir));
+    if (!options.dryRun) {
+      await sourceFile.save();
+    }
+  }
+  project.packageJson.scripts ??= {};
+  const run2 = packageScriptPrefix(project.packageManager);
+  const cap = capacitorScriptPrefix(project.packageManager);
+  project.packageJson.scripts["cap:sync"] = `${run2} build && ${cap} sync`;
+  for (const platform of options.platforms) {
+    project.packageJson.scripts[`cap:${platform}`] = `${run2} cap:sync && ${cap} open ${platform}`;
+  }
+  await savePackageJson(project, options.dryRun);
+}
+
+// src/capacitor/install.ts
+import path5 from "path";
+async function installCapacitor(project, platforms) {
+  const runtimePackages = [
+    "@capacitor/core",
+    ...platforms.map((platform) => `@capacitor/${platform}`)
+  ];
+  await run(project, installCommand(project.packageManager, runtimePackages, false));
+  await run(
+    project,
+    installCommand(project.packageManager, ["@capacitor/cli"], true)
+  );
+}
+async function buildProject(project) {
+  await run(project, runScriptCommand(project.packageManager, "build"));
+}
+async function addNativePlatforms(project, platforms) {
+  for (const platform of platforms) {
+    if (await pathExists(path5.join(project.root, platform))) {
+      continue;
+    }
+    await run(project, capacitorCommand(project.packageManager, ["add", platform]));
+  }
+}
+async function syncNativeProjects(project) {
+  await run(project, capacitorCommand(project.packageManager, ["sync"]));
+}
+async function run(project, [command, args]) {
+  await runCommand(command, args, project.root);
+}
+
+// src/core/framework-selection.ts
+import {
+  cancel,
+  confirm,
+  isCancel,
+  select
+} from "@clack/prompts";
+var terminalFrameworkPrompts = {
+  async confirmDetected(adapter) {
+    const answer = await confirm({
+      message: `Use the detected framework ${adapter.label}?`,
+      initialValue: true
+    });
+    return unwrapPrompt(answer);
+  },
+  async selectFramework(adapters2) {
+    const answer = await select({
+      message: "Which framework should Capstart configure?",
+      options: adapters2.map((adapter) => ({
+        value: adapter.id,
+        label: adapter.label
+      }))
+    });
+    return unwrapPrompt(answer);
+  }
+};
+async function chooseAdapter(options) {
+  if (options.requested) {
+    return getAdapter(options.requested);
+  }
+  if (options.detected.length === 1 && options.acceptDetected) {
+    return options.detected[0];
+  }
+  if (!options.interactive) {
+    if (options.detected.length === 1) {
+      throw new Error(
+        `Detected ${options.detected[0].label}, but confirmation requires an interactive terminal. Pass --yes to accept it or --framework to choose explicitly.`
+      );
+    }
+    throw new Error(
+      "Framework selection requires an interactive terminal. Pass --framework nextjs or --framework tanstack-start."
+    );
+  }
+  const prompts = options.prompts ?? terminalFrameworkPrompts;
+  if (options.detected.length === 1 && await prompts.confirmDetected(options.detected[0])) {
+    return options.detected[0];
+  }
+  return getAdapter(await prompts.selectFramework(getAdapters()));
+}
+function unwrapPrompt(value) {
+  if (isCancel(value)) {
+    cancel("Capstart initialization cancelled.");
+    throw new Error("Initialization cancelled.");
+  }
+  return value;
+}
+
+// src/core/github-star.ts
+import { confirm as confirm2, isCancel as isCancel2 } from "@clack/prompts";
+
+// src/core/logger.ts
+import pc from "picocolors";
+var logger = {
+  info(message) {
+    console.log(`${pc.cyan("\u2022")} ${message}`);
+  },
+  success(message) {
+    console.log(`${pc.green("\u2713")} ${message}`);
+  },
+  warning(message) {
+    console.log(`${pc.yellow("!")} ${message}`);
+  },
+  error(message) {
+    console.error(`${pc.red("\u2717")} ${message}`);
+  },
+  heading(message) {
+    console.log(`
+${pc.bold(message)}`);
+  },
+  link(url) {
+    console.log(`  ${pc.underline(pc.cyan(url))}`);
+  },
+  command(command, description) {
+    console.log(`  ${pc.cyan(command)}
+    ${pc.dim(description)}`);
+  },
+  detail(message) {
+    const lines = wrapText(message, getContentWidth());
+    console.log(
+      lines.map(
+        (line, index) => index === 0 ? `  ${pc.yellow("\u2022")} ${line}` : `    ${line}`
+      ).join("\n")
+    );
+  }
+};
+function getContentWidth() {
+  const terminalWidth = process.stdout.columns ?? 100;
+  return Math.max(40, Math.min(terminalWidth - 4, 80));
+}
+function wrapText(message, width) {
+  const lines = [];
+  let line = "";
+  for (const word of message.split(/\s+/)) {
+    if (line.length > 0 && line.length + word.length + 1 > width) {
+      lines.push(line);
+      line = word;
+      continue;
+    }
+    line = line.length === 0 ? word : `${line} ${word}`;
+  }
+  if (line.length > 0) {
+    lines.push(line);
+  }
+  return lines;
+}
+
+// src/core/github-star.ts
+var repository = "AdrienADV/capstart";
+var terminalGithubStarPrompt = {
+  async confirmStar() {
+    const answer = await confirm2({
+      message: "Would you like to star Capstart on GitHub?",
+      initialValue: true
+    });
+    return isCancel2(answer) ? false : answer;
+  }
+};
+async function offerGithubStar(options) {
+  if (!options.interactive) {
+    return "skipped";
+  }
+  const isGhInstalled = options.isGhInstalled ?? (() => commandExists("gh", ["--version"]));
+  if (!await isGhInstalled()) {
+    return "skipped";
+  }
+  const prompt = options.prompt ?? terminalGithubStarPrompt;
+  if (!await prompt.confirmStar()) {
+    return "declined";
+  }
+  const starRepository = options.starRepository ?? (() => runCommand(
+    "gh",
+    ["api", "--method", "PUT", `/user/starred/${repository}`],
+    options.cwd
+  ));
+  try {
+    await starRepository();
+    logger.success(`Starred https://github.com/${repository}`);
+    return "starred";
+  } catch {
+    logger.warning(
+      `Could not star ${repository}. Check your GitHub CLI authentication with "gh auth status".`
+    );
+    return "failed";
+  }
+}
+
+// src/core/progress.ts
+import { spinner } from "@clack/prompts";
+var silentProgress = {
+  message() {
+  },
+  start() {
+  },
+  stop() {
+  }
+};
+function createProgress(interactive) {
+  return interactive ? spinner() : silentProgress;
+}
+
+// src/commands/init.ts
+async function initCommand(options) {
+  const project = await loadProject(options.directory);
+  logger.heading("Capstart");
+  const detected = detectAdapters(project);
+  logDetection(detected);
+  const adapter = await chooseAdapter({
+    acceptDetected: options.yes,
+    detected,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    requested: options.framework
+  });
+  if (!detected.includes(adapter)) {
+    logger.warning(`${adapter.label} was selected but was not automatically detected.`);
+  }
+  const diagnostics = await adapter.validate(project);
+  for (const warning of diagnostics.filter((item) => item.level === "warning")) {
+    logger.warning(warning.message);
+  }
+  const errors = diagnostics.filter((item) => item.level === "error");
+  if (errors.length > 0) {
+    throw new Error(errors.map((error) => error.message).join("\n"));
+  }
+  const appId = options.appId ?? createDefaultAppId(project);
+  const appName = options.appName ?? getProjectName(project);
+  validateAppId(appId);
+  if (options.dryRun) {
+    const frameworkResult2 = await adapter.configure(project, true);
+    await configureCapacitor(project, {
+      appId,
+      appName,
+      dryRun: true,
+      platforms: options.platforms,
+      webDir: adapter.webDir
+    });
+    logger.heading("Planned changes");
+    logger.info(`Configure ${adapter.label} for Capacitor`);
+    logger.info(`Configure Capacitor with webDir "${adapter.webDir}"`);
+    logger.success("Dry run complete. No files were changed.");
+    printFinalGuidance(frameworkResult2.disclaimers);
+    return;
+  }
+  const frameworkResult = await runSetup({
+    adapter,
+    appId,
+    appName,
+    options,
+    project
+  });
+  logger.heading("Ready");
+  logger.success("Your base Capacitor setup is ready.");
+  logger.heading("Scripts added");
+  logger.command(
+    `${project.packageManager} run cap:sync`,
+    "Build the web app and sync the native projects."
+  );
+  if (options.platforms.includes("ios")) {
+    logger.command(
+      `${project.packageManager} run cap:ios`,
+      "Build, sync, and open the iOS project in Xcode."
+    );
+  }
+  if (options.platforms.includes("android")) {
+    logger.command(
+      `${project.packageManager} run cap:android`,
+      "Build, sync, and open the Android project in Android Studio."
+    );
+  }
+  logger.heading("Next steps");
+  logger.info(
+    "Review recommended plugins, native configuration, and production setup:"
+  );
+  logger.link(
+    "https://capstart.dev/docs/installation/#3-add-recommended-capacitor-base-plugins"
+  );
+  await offerGithubStar({
+    cwd: project.root,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY)
+  });
+  printFinalGuidance(frameworkResult.disclaimers);
+}
+async function runSetup(context) {
+  const { adapter, appId, appName, options, project } = context;
+  const progress = createProgress(Boolean(process.stdout.isTTY));
+  const frameworkResult = await runStep(
+    progress,
+    `Configure ${adapter.label}`,
+    () => adapter.configure(project, false)
+  );
+  await runStep(
+    progress,
+    "Configure Capacitor",
+    () => configureCapacitor(project, {
+      appId,
+      appName,
+      dryRun: false,
+      platforms: options.platforms,
+      webDir: adapter.webDir
+    })
+  );
+  if (!options.skipInstall) {
+    await runStep(
+      progress,
+      "Install Capacitor packages",
+      () => installCapacitor(project, options.platforms)
+    );
+  }
+  if (!options.skipBuild) {
+    await runStep(progress, "Build the web app", () => buildProject(project));
+  }
+  if (!options.skipNative) {
+    await runStep(
+      progress,
+      `Prepare ${formatPlatforms(options.platforms)} projects`,
+      () => addNativePlatforms(project, options.platforms)
+    );
+    await runStep(
+      progress,
+      "Synchronize native projects",
+      () => syncNativeProjects(project)
+    );
+  }
+  return frameworkResult;
+}
+async function runStep(progress, label, action) {
+  progress.start(label);
+  try {
+    const result = await action();
+    progress.stop(label);
+    return result;
+  } catch (error) {
+    progress.stop(`${label} failed`);
+    throw error;
+  }
+}
+function formatPlatforms(platforms) {
+  return platforms.map((platform) => platform === "ios" ? "iOS" : "Android").join(" and ");
+}
+function logDetection(detected) {
+  if (detected.length === 0) {
+    logger.warning("No supported framework was automatically detected.");
+    return;
+  }
+  if (detected.length === 1) {
+    logger.success(`Detected ${detected[0].label}`);
+    return;
+  }
+  logger.warning(
+    `Detected multiple frameworks: ${detected.map((adapter) => adapter.label).join(", ")}`
+  );
+}
+function validateAppId(appId) {
+  if (!/^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$/.test(appId)) {
+    throw new Error(
+      `Invalid app id "${appId}". Use reverse-domain notation, for example com.example.app.`
+    );
+  }
+}
+function printFinalGuidance(disclaimers) {
+  if (disclaimers.length === 0) {
+    return;
+  }
+  logger.heading("Important");
+  for (const disclaimer of disclaimers) {
+    logger.warning(disclaimer.title);
+    for (const detail of disclaimer.details) {
+      logger.detail(detail);
+    }
+  }
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("capstart").description("Add Capacitor to an existing web application.").version("0.1.0");
+program.command("init").description("Configure an existing application for Capacitor.").argument("[directory]", "project directory", ".").option(
+  "-f, --framework <framework>",
+  "framework adapter: nextjs or tanstack-start",
+  parseFramework
+).option("--app-id <id>", "native application id, for example com.example.app").option("--app-name <name>", "native application name").option(
+  "--platforms <platforms>",
+  "comma-separated native platforms",
+  parsePlatforms,
+  ["ios", "android"]
+).option("--skip-install", "do not install Capacitor packages").option("--skip-build", "do not build the web application").option("--skip-native", "do not add or synchronize native projects").option("--dry-run", "show configuration changes without writing files").option("-y, --yes", "accept the automatically detected framework").action(async (directory, commandOptions) => {
+  await initCommand({
+    appId: commandOptions.appId,
+    appName: commandOptions.appName,
+    directory,
+    dryRun: commandOptions.dryRun ?? false,
+    framework: commandOptions.framework,
+    platforms: commandOptions.platforms,
+    skipBuild: commandOptions.skipBuild ?? false,
+    skipInstall: commandOptions.skipInstall ?? false,
+    skipNative: commandOptions.skipNative ?? false,
+    yes: commandOptions.yes ?? false
+  });
+});
+program.parseAsync().catch((error) => {
+  logger.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});
+function parseFramework(value) {
+  if (value === "nextjs" || value === "tanstack-start") {
+    return value;
+  }
+  throw new InvalidArgumentError(
+    'Framework must be "nextjs" or "tanstack-start".'
+  );
+}
+function parsePlatforms(value) {
+  const platforms = value.split(",").map((platform) => platform.trim()).filter(Boolean);
+  if (platforms.length === 0 || platforms.some((platform) => platform !== "ios" && platform !== "android")) {
+    throw new InvalidArgumentError(
+      'Platforms must contain "ios", "android", or both.'
+    );
+  }
+  return [...new Set(platforms)];
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "capstart",
+  "version": "0.1.0",
+  "description": "Add Capacitor to existing web framework projects.",
+  "type": "module",
+  "bin": {
+    "capstart": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "capacitor",
+    "cli",
+    "mobile",
+    "nextjs",
+    "tanstack-start"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AdrienADV/capstart.git",
+    "directory": "cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --dts --clean",
+    "dev": "node --import tsx src/cli.ts",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "commander": "^14.0.2",
+    "picocolors": "^1.1.1",
+    "ts-morph": "^27.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}