@remix-run/cli 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+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

@@ -1,4 +1,81 @@
-# Placeholder Package
+# cli
 
-This package is a placeholder published at `0.0.0` to reserve the npm name and
-configure CI publish permissions.
+Command-line interface for creating and managing Remix projects.
+
+## Features
+
+- Create new Remix projects with `npx remix@next new` or installed `remix new`
+- Print shell completion scripts with `remix completion`
+- Check project environment and Remix app conventions with `remix doctor`
+- Create low-risk project and controller files with `remix doctor --fix`
+- Inspect the current app route tree with `remix routes`
+- Sync Remix skills into `.agents/skills` with `remix skills`
+- Run project tests with `remix test`
+- Print the current Remix version with `remix version`
+- Use the same CLI through the `remix` package or the `remix/cli` API
+- Scaffold a starter app that matches the Remix project layout conventions
+
+## Installation
+
+Use `npx remix@next new <target-dir>` to scaffold a new Remix app. Install `remix` when you want the local `remix` command:
+
+```sh
+npm i remix
+```
+
+## Shell completion
+
+Install bash completion:
+
+```sh
+remix completion bash >> ~/.bashrc
+```
+
+Install zsh completion:
+
+```sh
+remix completion zsh >> ~/.zshrc
+```
+
+## Usage
+
+Use `npx remix@next new my-remix-app` to scaffold a new Remix app. After installing Remix, the equivalent local command is `remix new my-remix-app`.
+
+The rest of the CLI is available through the installed `remix` command:
+
+```sh
+remix new my-remix-app
+remix completion bash >> ~/.bashrc
+remix doctor
+remix doctor --fix
+remix routes
+remix routes --table
+remix routes --table --no-headers
+remix skills install
+remix test
+remix version
+remix --no-color doctor
+```
+
+You can also run the CLI programmatically:
+
+```ts
+import { runRemix } from 'remix/cli'
+
+await runRemix(['new', 'my-remix-app'])
+await runRemix(['completion', 'bash'])
+await runRemix(['doctor'])
+await runRemix(['doctor', '--fix'])
+await runRemix(['routes'])
+await runRemix(['routes', '--table'])
+await runRemix(['routes', '--table', '--no-headers'])
+await runRemix(['skills', 'list'])
+await runRemix(['test'])
+await runRemix(['version'])
+```
+
+`runRemix()` returns the CLI exit code as a promise.
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/bootstrap/AGENTS.md

@@ -0,0 +1,35 @@
+# %%RMX_APP_DISPLAY_NAME%% Agent Guide
+
+This app was scaffolded with `remix new`. Use these conventions when continuing to build it out.
+
+## Commands
+
+```sh
+npm i
+npm run start
+npm test
+npm run typecheck
+```
+
+## Starter Layout
+
+- `app/controllers/home.tsx` owns the home page
+- `app/controllers/auth.tsx` owns the auth page
+- `app/routes.ts` defines the route contract
+- `app/router.ts` wires routes to route handlers
+- `app/ui/` holds the shared document and layout wrappers
+- `app/utils/render.tsx` centralizes HTML response rendering
+
+## Route Ownership
+
+- Start from `app/routes.ts` and map each route to the narrowest owner on disk.
+- Keep simple pages in flat files like `app/controllers/home.tsx` and `app/controllers/auth.tsx`.
+- Promote a route into a controller folder with `controller.tsx` only when it gains nested routes, multiple actions, or route-owned modules.
+- Keep route-owned page modules next to the route that owns them.
+- Move shared UI to `app/ui/`, not `app/controllers/`.
+
+## Build-Out Notes
+
+- This starter intentionally begins small; add directories like `app/data/`, `app/middleware/`, `public/`, and `test/` only when you need them.
+- Prefer putting code in the narrowest owner before introducing shared modules.
+- Avoid generic dumping-ground directories like `app/lib/` or `app/components/`.

package/bootstrap/README.md

@@ -0,0 +1,27 @@
+# %%RMX_APP_DISPLAY_NAME%%
+
+A minimal Remix application starter with a home page and an auth page.
+
+## Starter Shape
+
+- `app/controllers/home.tsx` owns the home page.
+- `app/controllers/auth.tsx` owns the auth page.
+- `app/routes.ts` defines the route contract.
+- `app/router.ts` wires routes to handlers.
+- `app/ui/` holds the shared document and layout wrappers.
+- `app/utils/render.tsx` centralizes HTML response rendering.
+
+## Growing The App
+
+- Start with flat route files and only introduce route folders when a route needs multiple actions or route-owned modules.
+- Add directories like `app/data/`, `app/middleware/`, `public/`, or `test/` when the app actually needs them.
+- Move shared UI into `app/ui/` once more than one route needs it.
+
+## Commands
+
+```sh
+npm i
+npm run start
+npm test
+npm run typecheck
+```

package/bootstrap/app/controllers/auth.tsx

@@ -0,0 +1,21 @@
+import type { BuildAction } from 'remix/fetch-router'
+
+import type { routes } from '../routes.ts'
+import { Layout } from '../ui/layout.tsx'
+import { render } from '../utils/render.tsx'
+
+export const auth: BuildAction<'GET', typeof routes.auth> = {
+  handler() {
+    return render(<AuthPage />)
+  },
+}
+
+function AuthPage() {
+  return () => (
+    <Layout title="Auth">
+      <h1>Auth</h1>
+      <p>Use this route to start building sign-in, sign-up, and session flows.</p>
+      <p>Keep it as a flat file until the route needs multiple actions or route-owned modules.</p>
+    </Layout>
+  )
+}

package/bootstrap/app/controllers/home.tsx

@@ -0,0 +1,26 @@
+import type { BuildAction } from 'remix/fetch-router'
+
+import type { routes } from '../routes.ts'
+import { Layout } from '../ui/layout.tsx'
+import { render } from '../utils/render.tsx'
+
+const APP_DISPLAY_NAME = decodeURIComponent('%%RMX_APP_DISPLAY_NAME_URI_COMPONENT%%')
+
+export const home: BuildAction<'GET', typeof routes.home> = {
+  handler() {
+    return render(<HomePage />)
+  },
+}
+
+function HomePage() {
+  return () => (
+    <Layout title="Home">
+      <h1>{APP_DISPLAY_NAME}</h1>
+      <p>This starter begins with two flat route files so you can start shipping immediately.</p>
+      <p>
+        Add new routes in <code>app/routes.ts</code>, keep them flat at first, and only split them
+        into folders when the route grows.
+      </p>
+    </Layout>
+  )
+}

package/bootstrap/app/router.ts

@@ -0,0 +1,10 @@
+import { createRouter } from 'remix/fetch-router'
+
+import { auth } from './controllers/auth.tsx'
+import { home } from './controllers/home.tsx'
+import { routes } from './routes.ts'
+
+export const router = createRouter()
+
+router.map(routes.home, home)
+router.map(routes.auth, auth)

package/bootstrap/app/routes.ts

@@ -0,0 +1,6 @@
+import { route } from 'remix/fetch-router/routes'
+
+export const routes = route({
+  home: '/',
+  auth: '/auth',
+})

package/bootstrap/app/ui/document.tsx

@@ -0,0 +1,21 @@
+import type { RemixNode } from 'remix/ui'
+
+export interface DocumentProps {
+  children?: RemixNode
+  title?: string
+}
+
+const DEFAULT_TITLE = decodeURIComponent('%%RMX_APP_DISPLAY_NAME_URI_COMPONENT%%')
+
+export function Document() {
+  return ({ title = DEFAULT_TITLE, children }: DocumentProps) => (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>{title}</title>
+      </head>
+      <body>{children}</body>
+    </html>
+  )
+}

package/bootstrap/app/ui/layout.tsx

@@ -0,0 +1,22 @@
+import type { RemixNode } from 'remix/ui'
+
+import { routes } from '../routes.ts'
+import { Document } from './document.tsx'
+
+export interface LayoutProps {
+  children?: RemixNode
+  title?: string
+}
+
+export function Layout() {
+  return ({ title, children }: LayoutProps) => (
+    <Document title={title}>
+      <header>
+        <nav>
+          <a href={routes.home.href()}>Home</a> <a href={routes.auth.href()}>Auth</a>
+        </nav>
+      </header>
+      <main>{children}</main>
+    </Document>
+  )
+}

package/bootstrap/app/utils/render.tsx

@@ -0,0 +1,7 @@
+import type { RemixNode } from 'remix/ui'
+import { renderToStream } from 'remix/ui/server'
+import { createHtmlResponse } from 'remix/response/html'
+
+export function render(node: RemixNode, init?: ResponseInit) {
+  return createHtmlResponse(renderToStream(node), init)
+}

package/bootstrap/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "remix-bootstrap-template",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "start": "tsx server.ts",
+    "test": "tsx --test",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=24.3.0"
+  },
+  "dependencies": {
+    "remix": "workspace:^",
+    "tsx": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:"
+  }
+}

package/bootstrap/server.ts

@@ -0,0 +1,37 @@
+import * as http from 'node:http'
+import { createRequestListener } from 'remix/node-fetch-server'
+
+import { router } from './app/router.ts'
+
+const server = http.createServer(
+  createRequestListener(async (request) => {
+    try {
+      return await router.fetch(request)
+    } catch (error) {
+      console.error(error)
+      return new Response('Internal Server Error', { status: 500 })
+    }
+  }),
+)
+
+const port = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 44100
+
+server.listen(port, () => {
+  console.log(`Server listening on http://localhost:${port}`)
+})
+
+let shuttingDown = false
+
+function shutdown() {
+  if (shuttingDown) {
+    return
+  }
+
+  shuttingDown = true
+  server.close(() => {
+    process.exit(0)
+  })
+}
+
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)

package/bootstrap/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "types": ["node"],
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "target": "ESNext",
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "remix/ui",
+    "preserveSymlinks": true,
+    "noEmit": true
+  },
+  "exclude": ["dist"]
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { runRemix, type RunRemixOptions } from './lib/cli.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { runRemix } from "./lib/cli.js";

package/dist/lib/bootstrap-project.d.ts

@@ -0,0 +1,17 @@
+import { type StepProgressReporter } from './reporter.ts';
+export declare const MINIMUM_SUPPORTED_NODE_VERSION = "24.3.0";
+export interface BootstrapProjectOptions {
+    appName: string | null;
+    cwd?: string;
+    force: boolean;
+    remixVersion?: string;
+    targetDir: string;
+}
+export type BootstrapProjectPhase = 'prepare-target-directory' | 'generate-scaffold-files' | 'finalize-package-json';
+export interface BootstrappedProject {
+    appDisplayName: string;
+    targetDir: string;
+}
+export type BootstrapProgressReporter = StepProgressReporter<BootstrapProjectPhase>;
+export declare function bootstrapProject(options: BootstrapProjectOptions, progress?: BootstrapProgressReporter): Promise<BootstrappedProject>;
+//# sourceMappingURL=bootstrap-project.d.ts.map

package/dist/lib/bootstrap-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-project.d.ts","sourceRoot":"","sources":["../../src/lib/bootstrap-project.ts"],"names":[],"mappings":"AAYA,OAAO,EAAmB,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAO1E,eAAO,MAAM,8BAA8B,WAAW,CAAA;AAEtD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,qBAAqB,GAC7B,0BAA0B,GAC1B,yBAAyB,GACzB,uBAAuB,CAAA;AAE3B,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,CAAC,qBAAqB,CAAC,CAAA;AAUnF,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,yBAAyB,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAgC9B"}

package/dist/lib/bootstrap-project.js

@@ -0,0 +1,137 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import semver from 'semver';
+import { appNameUnavailable, invalidPackageName, targetDirectoryNotEmpty, targetPathNotDirectory, } from "./errors.js";
+import { runProgressStep } from "./reporter.js";
+const BOOTSTRAP_DIRECTORY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bootstrap');
+const BOOTSTRAP_EXCLUDED_NAMES = new Set(['.gitkeep', 'node_modules']);
+export const MINIMUM_SUPPORTED_NODE_VERSION = '24.3.0';
+export async function bootstrapProject(options, progress) {
+    let cwd = options.cwd ?? process.cwd();
+    let targetDir = path.resolve(cwd, options.targetDir);
+    let rawAppName = options.appName ?? path.basename(targetDir);
+    if (rawAppName.length === 0) {
+        throw appNameUnavailable(targetDir);
+    }
+    let config = {
+        appDisplayName: options.appName ?? humanizeName(rawAppName),
+        packageName: toPackageName(rawAppName),
+        remixVersion: readDefaultRemixVersion(options.remixVersion),
+    };
+    await runProgressStep(progress, 'prepare-target-directory', () => ensureTargetDirectory(targetDir, options.force));
+    await runProgressStep(progress, 'generate-scaffold-files', () => copyBootstrapDirectory({
+        sourceDir: BOOTSTRAP_DIRECTORY,
+        targetDir,
+        templateValues: createTemplateValues(config),
+    }));
+    await runProgressStep(progress, 'finalize-package-json', () => writeScaffoldPackageJson(targetDir, config));
+    return {
+        appDisplayName: config.appDisplayName,
+        targetDir,
+    };
+}
+function readDefaultRemixVersion(runtimeVersion) {
+    let overriddenVersion = process.env.REMIX_VERSION?.trim();
+    if (overriddenVersion) {
+        return overriddenVersion;
+    }
+    if (runtimeVersion == null) {
+        return 'latest';
+    }
+    let validRuntimeVersion = semver.valid(runtimeVersion);
+    return validRuntimeVersion == null ? runtimeVersion : `^${validRuntimeVersion}`;
+}
+function createTemplateValues(config) {
+    return {
+        '%%RMX_APP_DISPLAY_NAME%%': config.appDisplayName,
+        '%%RMX_APP_DISPLAY_NAME_URI_COMPONENT%%': encodeURIComponent(config.appDisplayName),
+    };
+}
+async function writeScaffoldPackageJson(targetDir, config) {
+    let packageJsonPath = path.join(targetDir, 'package.json');
+    let packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+    packageJson.name = config.packageName;
+    packageJson.dependencies = {
+        ...packageJson.dependencies,
+        remix: config.remixVersion,
+        tsx: 'latest',
+    };
+    packageJson.devDependencies = {
+        ...packageJson.devDependencies,
+        '@types/node': 'latest',
+        typescript: 'latest',
+    };
+    packageJson.engines = {
+        ...packageJson.engines,
+        node: `>=${MINIMUM_SUPPORTED_NODE_VERSION}`,
+    };
+    await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n', 'utf8');
+}
+async function ensureTargetDirectory(targetDir, force) {
+    try {
+        let stats = await fs.stat(targetDir);
+        if (!stats.isDirectory()) {
+            throw targetPathNotDirectory(targetDir);
+        }
+        let entries = await fs.readdir(targetDir);
+        if (entries.length > 0 && !force) {
+            throw targetDirectoryNotEmpty(targetDir);
+        }
+    }
+    catch (error) {
+        let nodeError = error;
+        if (nodeError.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    await fs.mkdir(targetDir, { recursive: true });
+}
+async function copyBootstrapDirectory({ sourceDir, targetDir, templateValues, }) {
+    let entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    for (let entry of entries) {
+        let sourcePath = path.join(sourceDir, entry.name);
+        let targetPath = path.join(targetDir, entry.name);
+        if (BOOTSTRAP_EXCLUDED_NAMES.has(entry.name)) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await fs.mkdir(targetPath, { recursive: true });
+            await copyBootstrapDirectory({ sourceDir: sourcePath, targetDir: targetPath, templateValues });
+            continue;
+        }
+        let content = await fs.readFile(sourcePath, 'utf8');
+        await fs.writeFile(targetPath, replaceTemplateValues(content, templateValues), 'utf8');
+    }
+}
+function replaceTemplateValues(content, templateValues) {
+    for (let [token, value] of Object.entries(templateValues)) {
+        content = content.split(token).join(value);
+    }
+    return content;
+}
+function humanizeName(value) {
+    let parts = value.split(/[-_\s]+/).filter(Boolean);
+    if (parts.length === 0) {
+        return 'Remix App';
+    }
+    return parts
+        .map((part) => {
+        let head = part.slice(0, 1).toUpperCase();
+        let tail = part.slice(1);
+        return `${head}${tail}`;
+    })
+        .join(' ');
+}
+function toPackageName(value) {
+    let packageName = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (packageName.length === 0) {
+        throw invalidPackageName(value);
+    }
+    return packageName;
+}

package/dist/lib/cli-context.d.ts

@@ -0,0 +1,11 @@
+interface ResolveCliContextOptions {
+    cwd?: string;
+    remixVersion?: string;
+}
+export interface CliContext {
+    cwd: string;
+    remixVersion?: string;
+}
+export declare function resolveCliContext(options?: ResolveCliContextOptions): Promise<CliContext>;
+export {};
+//# sourceMappingURL=cli-context.d.ts.map

package/dist/lib/cli-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-context.d.ts","sourceRoot":"","sources":["../../src/lib/cli-context.ts"],"names":[],"mappings":"AAKA,UAAU,wBAAwB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,UAAU,CAAC,CAQrB"}

package/dist/lib/cli-context.js

@@ -0,0 +1,19 @@
+import * as path from 'node:path';
+import * as process from 'node:process';
+import { resolveDefaultRemixVersion } from "./remix-version.js";
+export async function resolveCliContext(options = {}) {
+    let cwd = resolveCwd(options.cwd);
+    let remixVersion = normalizeRemixVersion(options.remixVersion);
+    return {
+        cwd,
+        remixVersion: remixVersion ?? (await resolveDefaultRemixVersion(cwd)),
+    };
+}
+function resolveCwd(cwd) {
+    let normalizedCwd = cwd?.trim();
+    return path.resolve(normalizedCwd == null || normalizedCwd.length === 0 ? process.cwd() : normalizedCwd);
+}
+function normalizeRemixVersion(remixVersion) {
+    let normalizedVersion = remixVersion?.trim();
+    return normalizedVersion == null || normalizedVersion.length === 0 ? undefined : normalizedVersion;
+}

package/dist/lib/cli.d.ts

@@ -0,0 +1,6 @@
+export interface RunRemixOptions {
+    cwd?: string;
+    remixVersion?: string;
+}
+export declare function runRemix(argv?: string[], options?: RunRemixOptions): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/lib/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/lib/cli.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,wBAAsB,QAAQ,CAC5B,IAAI,GAAE,MAAM,EAA0B,EACtC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CA4BjB"}