feat(create-deepcrawl): enhance environment file handling and add API_URL support in configuration

Author: lumpinif

apps/app/components/www/create-deepcrawl-terminal.tsx

@@ -50,6 +50,8 @@ const TERMINAL_LINES: TerminalLine[] = [
     delay: 120,
     tone: 'default',
   },
+  // "Faircrawl" is intentional here. This demo deliberately leans into a
+  // Firecrawl-adjacent naming joke for the terminal sequence.
   { text: '│ Faircrawl', delay: 140, tone: 'accent' },
   { text: '', delay: 90 },
   { text: '◇ Choose what to deploy', delay: 120, tone: 'default' },
@@ -60,6 +62,7 @@ const TERMINAL_LINES: TerminalLine[] = [
   { text: '', delay: 90 },
   { text: 'wait... creating your project', delay: 180, tone: 'muted' },
   {
+    // Keep the product name aligned with the intentional "Faircrawl" demo copy above.
     text: '🎉 Your Faircrawl is ready. Do you want to test your API now?',
     delay: 120,
     tone: 'accent',

apps/app/components/www/installer.tsx

@@ -70,6 +70,9 @@ export const CommandInstaller = ({
             {code}
           </pre>
           <Button
+            aria-label={
+              isCopied ? 'Installer command copied' : 'Copy installer command'
+            }
             className="absolute right-1 rounded-sm bg-transparent! text-muted-foreground group-hover:text-foreground"
             onClick={(event) => {
               event.stopPropagation();
@@ -89,6 +92,9 @@ export const CommandInstaller = ({
             {code}
           </pre>
           <Button
+            aria-label={
+              isCopied ? 'Installer command copied' : 'Copy installer command'
+            }
             className="justify-self-center rounded-sm bg-transparent! text-muted-foreground group-hover:text-foreground"
             onClick={(event) => {
               event.stopPropagation();

packages/create-deepcrawl/src/__tests__/env-file.test.ts

@@ -36,3 +36,15 @@ test('upsertEnvFile updates JWT_SECRET and keeps other lines', () => {
   assert.match(output, /JWT_SECRET=second-secret/);
   assert.equal(output.match(/JWT_SECRET=/g)?.length, 1);
 });
+
+test('upsertEnvFile quotes values that would break dotenv parsing', () => {
+  const root = mkdtempSync(join(tmpdir(), 'create-deepcrawl-env-'));
+  const filePath = join(root, '.dev.vars');
+
+  upsertEnvFile(filePath, {
+    JWT_SECRET: 'abc#def with spaces',
+  });
+
+  const output = readFileSync(filePath, 'utf8');
+  assert.match(output, /JWT_SECRET="abc#def with spaces"/);
+});

packages/create-deepcrawl/src/__tests__/patch-v0-wrangler.test.ts

@@ -62,6 +62,7 @@ test('patchV0WranglerConfigForDeployment rebuilds production vars from allowlist
   assert.deepEqual(data.vars, {
     AUTH_MODE: 'jwt',
     ENABLE_ACTIVITY_LOGS: true,
+    API_URL: 'http://localhost:8080',
     WORKER_NODE_ENV: 'development',
     JWT_ISSUER: 'issuer-1',
     JWT_AUDIENCE: 'audience-1',
@@ -104,6 +105,7 @@ test('patchV0WranglerConfigForDeployment keeps optional jwt vars discoverable wh
   assert.deepEqual(data.vars, {
     AUTH_MODE: 'none',
     ENABLE_ACTIVITY_LOGS: false,
+    API_URL: 'http://localhost:8080',
     WORKER_NODE_ENV: 'development',
     JWT_ISSUER: '',
     JWT_AUDIENCE: '',

packages/create-deepcrawl/src/__tests__/prepare-v0-local-project.test.ts

@@ -63,6 +63,7 @@ test('prepareV0LocalProject aligns local wrangler config and JWT secret files',
   assert.deepEqual(data.vars, {
     AUTH_MODE: 'jwt',
     ENABLE_ACTIVITY_LOGS: false,
+    API_URL: 'http://localhost:8080',
     WORKER_NODE_ENV: 'development',
     JWT_ISSUER: 'issuer-1',
     JWT_AUDIENCE: 'audience-1',
@@ -87,3 +88,60 @@ test('prepareV0LocalProject aligns local wrangler config and JWT secret files',
     /JWT_SECRET=generated-secret/,
   );
 });
+
+test('prepareV0LocalProject keeps no-auth local config aligned without secret files', async () => {
+  const projectDir = await createProjectFixture();
+
+  const result = await prepareV0LocalProject({
+    projectDir,
+    projectName: 'My Deepcrawl',
+    authMode: 'none',
+    enableActivityLogs: true,
+  });
+
+  const next = await readFile(
+    join(projectDir, 'apps', 'workers', 'v0', 'wrangler.jsonc'),
+    'utf8',
+  );
+  const data = parse(next) as {
+    vars?: Record<string, string | boolean>;
+    env?: {
+      production?: {
+        vars?: Record<string, string | boolean>;
+      };
+    };
+  };
+
+  assert.equal(result.localJwtSecretFiles, undefined);
+  assert.deepEqual(data.vars, {
+    AUTH_MODE: 'none',
+    ENABLE_ACTIVITY_LOGS: true,
+    API_URL: 'http://localhost:8080',
+    WORKER_NODE_ENV: 'development',
+    JWT_ISSUER: '',
+    JWT_AUDIENCE: '',
+    ENABLE_API_RATE_LIMIT: false,
+  });
+  assert.deepEqual(data.env?.production?.vars, {
+    AUTH_MODE: 'none',
+    ENABLE_ACTIVITY_LOGS: true,
+    WORKER_NODE_ENV: 'production',
+    JWT_ISSUER: '',
+    JWT_AUDIENCE: '',
+    ENABLE_API_RATE_LIMIT: false,
+  });
+});
+
+test('prepareV0LocalProject rejects jwt mode without a secret', async () => {
+  const projectDir = await createProjectFixture();
+
+  await assert.rejects(
+    prepareV0LocalProject({
+      projectDir,
+      projectName: 'My Deepcrawl',
+      authMode: 'jwt',
+      enableActivityLogs: false,
+    }),
+    /JWT secret is missing/,
+  );
+});

packages/create-deepcrawl/src/lib/env-file.ts

@@ -3,6 +3,10 @@ import { dirname } from 'node:path';
 
 type EnvUpdates = Record<string, string>;
 
+function formatEnvValue(value: string): string {
+  return /^[A-Za-z0-9_./:-]+$/.test(value) ? value : JSON.stringify(value);
+}
+
 function getDefaultHeader(filePath: string): string[] {
   if (filePath.endsWith('.dev.vars.production')) {
     return [
@@ -48,7 +52,7 @@ export function upsertEnvFile(filePath: string, updates: EnvUpdates): void {
     }
 
     seen.add(key);
-    return `${key}=${updates[key]}`;
+    return `${key}=${formatEnvValue(updates[key])}`;
   });
 
   for (const [key, value] of Object.entries(updates)) {
@@ -63,7 +67,7 @@ export function upsertEnvFile(filePath: string, updates: EnvUpdates): void {
       updatedLines.push('# JWT');
     }
 
-    updatedLines.push(`${key}=${value}`);
+    updatedLines.push(`${key}=${formatEnvValue(value)}`);
   }
 
   const output = updatedLines

packages/create-deepcrawl/src/steps/patch-v0-wrangler.ts

@@ -10,6 +10,7 @@ type ParsedWranglerConfig = {
   d1_databases?: Array<{
     migrations_dir?: string;
   }>;
+  vars?: Record<string, string | boolean>;
 };
 
 function normalizeWorkerName(projectName: string): string {
@@ -30,6 +31,12 @@ function getExistingMigrationsDir(source: string): string | null {
   return typeof migrations === 'string' ? migrations : null;
 }
 
+function getExistingLocalApiUrl(source: string): string | null {
+  const data = parse(source) as ParsedWranglerConfig;
+  const apiUrl = data?.vars?.API_URL;
+  return typeof apiUrl === 'string' ? apiUrl : null;
+}
+
 function buildSharedWorkerVars(input: {
   authMode: AuthMode;
   enableActivityLogs: boolean;
@@ -114,6 +121,10 @@ export async function patchV0WranglerConfigForDeployment({
         jwtIssuer,
         jwtAudience,
       });
+      const localApiUrl = getExistingLocalApiUrl(source);
+      if (localApiUrl) {
+        rootVars.API_URL = localApiUrl;
+      }
       const deploymentVars = buildProductionVars({
         authMode,
         enableActivityLogs,