better-cf 0.1.0 → 0.2.2

package/dist/cli/index.js

@@ -1,13 +1,54 @@
 import { Command } from 'commander';
 import pc from 'picocolors';
 import { spawn } from 'child_process';
-import fs7 from 'fs';
+import fs8 from 'fs';
 import path3 from 'path';
 import { Project, SyntaxKind, Node } from 'ts-morph';
 import { applyEdits, modify, parse } from 'jsonc-parser';
 import chokidar from 'chokidar';
+import { createInterface } from 'readline/promises';
+import { stdin, stdout } from 'process';
 
 // src/cli/index.ts
+
+// src/cli/errors.ts
+var CliError = class extends Error {
+  code;
+  summary;
+  file;
+  details;
+  hint;
+  docsUrl;
+  constructor(options) {
+    super(options.summary);
+    this.name = "CliError";
+    this.code = options.code;
+    this.summary = options.summary;
+    this.file = options.file;
+    this.details = options.details;
+    this.hint = options.hint;
+    this.docsUrl = options.docsUrl;
+    if (options.cause !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+function toCliError(error) {
+  if (error instanceof CliError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new CliError({
+      code: "UNEXPECTED_ERROR",
+      summary: error.message,
+      details: error.stack
+    });
+  }
+  return new CliError({
+    code: "UNEXPECTED_ERROR",
+    summary: String(error)
+  });
+}
 function printLine(message) {
   process.stdout.write(`${message}
 `);
@@ -38,6 +79,33 @@ var logger = {
   },
   item(label, value) {
     printLine(`  -> ${pc.bold(label)}${value ? `: ${value}` : ""}`);
+  },
+  diagnostic(diag) {
+    const levelBadge = diag.level === "error" ? pc.red("[error]") : pc.yellow("[warn]");
+    printLine(`${levelBadge} ${pc.bold(diag.code)} ${diag.message}`);
+    if (diag.filePath) {
+      printLine(`      file: ${diag.filePath}`);
+    }
+    if (diag.hint) {
+      printLine(`      hint: ${diag.hint}`);
+    }
+  },
+  cliError(payload) {
+    printErrLine(pc.red(pc.bold(`
+ERROR ${payload.code}`)));
+    printErrLine(pc.red(payload.summary));
+    if (payload.file) {
+      printErrLine(`  file: ${payload.file}`);
+    }
+    if (payload.details) {
+      printErrLine(`  details: ${payload.details}`);
+    }
+    if (payload.hint) {
+      printErrLine(`  hint: ${payload.hint}`);
+    }
+    if (payload.docsUrl) {
+      printErrLine(`  docs: ${payload.docsUrl}`);
+    }
   }
 };
 function runCommand(command, args, cwd, stdio = "inherit") {
@@ -51,6 +119,31 @@ function runCommand(command, args, cwd, stdio = "inherit") {
     child.once("close", (code) => resolve(code ?? 0));
   });
 }
+function runCommandCapture(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: "pipe",
+      env: process.env
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.once("error", (error) => reject(error));
+    child.once("close", (code) => {
+      resolve({
+        code: code ?? 0,
+        stdout,
+        stderr
+      });
+    });
+  });
+}
 function spawnCommand(command, args, cwd) {
   return spawn(command, args, {
     cwd,
@@ -58,16 +151,241 @@ function spawnCommand(command, args, cwd) {
     env: process.env
   });
 }
+
+// src/cli/commands/admin.ts
+async function runWranglerQueueSubcommand(args, rootDir = process.cwd(), summary = "Wrangler queue command failed.") {
+  logger.section(`wrangler ${args.join(" ")}`);
+  const code = await runCommand("npx", ["wrangler", ...args], rootDir, "inherit");
+  if (code !== 0) {
+    throw new CliError({
+      code: "WRANGLER_QUEUE_COMMAND_FAILED",
+      summary,
+      details: `Command "wrangler ${args.join(" ")}" exited with code ${code}.`,
+      hint: "Verify wrangler auth/project configuration and command arguments.",
+      docsUrl: "https://developers.cloudflare.com/queues/reference/wrangler-commands/"
+    });
+  }
+}
+async function queueListCommand(rootDir = process.cwd()) {
+  await runWranglerQueueSubcommand(["queues", "list"], rootDir, "Failed to list queues.");
+}
+async function queueCreateCommand(name, options = {}, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", name);
+  const args = ["queues", "create", name];
+  pushNumberOption(args, "--delivery-delay-secs", options.deliveryDelaySecs);
+  pushNumberOption(args, "--message-retention-period-secs", options.messageRetentionPeriodSecs);
+  await runWranglerQueueSubcommand(
+    args,
+    rootDir,
+    `Failed to create queue "${name}".`
+  );
+}
+async function queueUpdateCommand(name, options = {}, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", name);
+  const args = ["queues", "update", name];
+  pushNumberOption(args, "--delivery-delay-secs", options.deliveryDelaySecs);
+  pushNumberOption(args, "--message-retention-period-secs", options.messageRetentionPeriodSecs);
+  await runWranglerQueueSubcommand(
+    args,
+    rootDir,
+    `Failed to update queue "${name}".`
+  );
+}
+async function queueDeleteCommand(name, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", name);
+  await runWranglerQueueSubcommand(
+    ["queues", "delete", name],
+    rootDir,
+    `Failed to delete queue "${name}".`
+  );
+}
+async function queueInfoCommand(name, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", name);
+  await runWranglerQueueSubcommand(["queues", "info", name], rootDir, `Failed to get queue "${name}".`);
+}
+async function queuePauseCommand(name, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", name);
+  await runWranglerQueueSubcommand(
+    ["queues", "pause-delivery", name],
+    rootDir,
+    `Failed to pause queue "${name}".`
+  );
+}
+async function queueResumeCommand(name, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", name);
+  await runWranglerQueueSubcommand(
+    ["queues", "resume-delivery", name],
+    rootDir,
+    `Failed to resume queue "${name}".`
+  );
+}
+async function queuePurgeCommand(name, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", name);
+  await runWranglerQueueSubcommand(
+    ["queues", "purge", name],
+    rootDir,
+    `Failed to purge queue "${name}".`
+  );
+}
+async function queueConsumerHttpAddCommand(queue, options = {}, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", queue);
+  const args = ["queues", "consumer", "http", "add", queue];
+  pushNumberOption(args, "--batch-size", options.batchSize);
+  pushNumberOption(args, "--message-retries", options.messageRetries);
+  pushStringOption(args, "--dead-letter-queue", options.deadLetterQueue);
+  pushNumberOption(args, "--visibility-timeout-secs", options.visibilityTimeoutSecs);
+  pushNumberOption(args, "--retry-delay-secs", options.retryDelaySecs);
+  await runWranglerQueueSubcommand(
+    args,
+    rootDir,
+    `Failed to add HTTP consumer for queue "${queue}".`
+  );
+}
+async function queueConsumerHttpRemoveCommand(queue, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", queue);
+  await runWranglerQueueSubcommand(
+    ["queues", "consumer", "http", "remove", queue],
+    rootDir,
+    `Failed to remove HTTP consumer for queue "${queue}".`
+  );
+}
+async function queueConsumerWorkerAddCommand(queue, script, options = {}, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", queue);
+  assertWranglerToken("worker script name", script);
+  const args = ["queues", "consumer", "worker", "add", queue, script];
+  pushNumberOption(args, "--batch-size", options.batchSize);
+  pushNumberOption(args, "--batch-timeout", options.batchTimeout);
+  pushNumberOption(args, "--message-retries", options.messageRetries);
+  pushStringOption(args, "--dead-letter-queue", options.deadLetterQueue);
+  pushNumberOption(args, "--max-concurrency", options.maxConcurrency);
+  pushNumberOption(args, "--retry-delay-secs", options.retryDelaySecs);
+  await runWranglerQueueSubcommand(
+    args,
+    rootDir,
+    `Failed to add worker consumer for queue "${queue}".`
+  );
+}
+async function queueConsumerWorkerRemoveCommand(queue, script, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", queue);
+  assertWranglerToken("worker script name", script);
+  await runWranglerQueueSubcommand(
+    ["queues", "consumer", "worker", "remove", queue, script],
+    rootDir,
+    `Failed to remove worker consumer for queue "${queue}".`
+  );
+}
+async function subscriptionListCommand(queue, options = {}, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", queue);
+  const args = ["queues", "subscription", "list", queue];
+  pushNumberOption(args, "--page", options.page);
+  pushNumberOption(args, "--per-page", options.perPage);
+  pushBooleanFlag(args, "--json", options.json);
+  await runWranglerQueueSubcommand(
+    args,
+    rootDir,
+    "Failed to list queue subscriptions."
+  );
+}
+async function subscriptionCreateCommand(queue, options, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", queue);
+  assertWranglerToken("subscription source", options.source);
+  const args = ["queues", "subscription", "create", queue, "--source", options.source, "--events", options.events];
+  pushStringOption(args, "--name", options.name);
+  pushBooleanOption(args, "--enabled", options.enabled);
+  pushStringOption(args, "--model-name", options.modelName);
+  pushStringOption(args, "--worker-name", options.workerName);
+  pushStringOption(args, "--workflow-name", options.workflowName);
+  await runWranglerQueueSubcommand(
+    args,
+    rootDir,
+    "Failed to create queue subscription."
+  );
+}
+async function subscriptionGetCommand(queue, id, options = {}, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", queue);
+  assertWranglerToken("subscription id", id);
+  const args = ["queues", "subscription", "get", queue, "--id", id];
+  pushBooleanFlag(args, "--json", options.json);
+  await runWranglerQueueSubcommand(
+    args,
+    rootDir,
+    `Failed to get queue subscription "${id}" from "${queue}".`
+  );
+}
+async function subscriptionUpdateCommand(queue, id, options, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", queue);
+  assertWranglerToken("subscription id", id);
+  const args = ["queues", "subscription", "update", queue, "--id", id];
+  pushStringOption(args, "--name", options.name);
+  pushStringOption(args, "--events", options.events);
+  pushBooleanOption(args, "--enabled", options.enabled);
+  pushBooleanFlag(args, "--json", options.json);
+  await runWranglerQueueSubcommand(
+    args,
+    rootDir,
+    `Failed to update queue subscription "${id}" on "${queue}".`
+  );
+}
+async function subscriptionDeleteCommand(queue, id, options = {}, rootDir = process.cwd()) {
+  assertWranglerToken("queue name", queue);
+  assertWranglerToken("subscription id", id);
+  const args = ["queues", "subscription", "delete", queue, "--id", id];
+  pushBooleanFlag(args, "--force", options.force);
+  await runWranglerQueueSubcommand(
+    args,
+    rootDir,
+    `Failed to delete queue subscription "${id}" from "${queue}".`
+  );
+}
+function pushStringOption(target, flag, value) {
+  if (value && value.length > 0) {
+    target.push(flag, value);
+  }
+}
+function pushNumberOption(target, flag, value) {
+  if (value !== void 0) {
+    target.push(flag, String(value));
+  }
+}
+function pushBooleanOption(target, flag, value) {
+  if (value !== void 0) {
+    target.push(flag, String(value));
+  }
+}
+function pushBooleanFlag(target, flag, value) {
+  if (value) {
+    target.push(flag);
+  }
+}
+function assertWranglerToken(label, value) {
+  if (!value || value.trim().length === 0) {
+    throw new CliError({
+      code: "INVALID_WRANGLER_ARGUMENT",
+      summary: `Invalid ${label}.`,
+      details: "Value cannot be empty.",
+      hint: `Provide a non-empty ${label}.`
+    });
+  }
+  if (value.startsWith("-")) {
+    throw new CliError({
+      code: "INVALID_WRANGLER_ARGUMENT",
+      summary: `Invalid ${label}.`,
+      details: `Value "${value}" starts with "-" and may be interpreted as a CLI flag.`,
+      hint: `Use a ${label} that does not start with "-".`
+    });
+  }
+}
 var DEFAULT_IGNORE = ["node_modules", ".better-cf", "dist", ".wrangler"];
 function loadCliConfig(rootDir = process.cwd()) {
   const defaults = {
     rootDir,
     ignore: [...DEFAULT_IGNORE],
     workerEntry: void 0,
-    legacyServiceWorker: false
+    legacyServiceWorker: false,
+    inferEnvTypes: true
   };
   const configPath = path3.join(rootDir, "better-cf.config.ts");
-  if (!fs7.existsSync(configPath)) {
+  if (!fs8.existsSync(configPath)) {
     return defaults;
   }
   const project = new Project({
@@ -89,11 +407,13 @@ function loadCliConfig(rootDir = process.cwd()) {
   const configObject = initializer;
   const workerEntry = readString(configObject, "workerEntry");
   const legacyServiceWorker = readBoolean(configObject, "legacyServiceWorker");
+  const inferEnvTypes = readBoolean(configObject, "inferEnvTypes");
   const ignore = readStringArray(configObject, "ignore");
   return {
     rootDir,
     workerEntry,
     legacyServiceWorker: legacyServiceWorker ?? defaults.legacyServiceWorker,
+    inferEnvTypes: inferEnvTypes ?? defaults.inferEnvTypes,
     ignore: ignore ? [.../* @__PURE__ */ new Set([...defaults.ignore, ...ignore])] : defaults.ignore
   };
 }
@@ -153,7 +473,7 @@ function resolveWorkerEntry(config) {
   ].filter((value) => Boolean(value));
   for (const candidate of candidates) {
     const absolutePath = path3.isAbsolute(candidate) ? candidate : path3.join(config.rootDir, candidate);
-    if (fs7.existsSync(absolutePath)) {
+    if (fs8.existsSync(absolutePath)) {
       return absolutePath;
     }
   }
@@ -165,14 +485,14 @@ function resolveWorkerEntry(config) {
 // src/cli/codegen.ts
 function generateCode(discovery, config) {
   const outputDir = path3.join(config.rootDir, ".better-cf");
-  fs7.mkdirSync(outputDir, { recursive: true });
+  fs8.mkdirSync(outputDir, { recursive: true });
   const workerEntryAbsolute = resolveWorkerEntry(config);
   const entryContents = renderEntryFile(discovery, workerEntryAbsolute, outputDir, config);
   const typesContents = renderTypesFile(discovery);
   const entryPath = path3.join(outputDir, "entry.ts");
   const typesPath = path3.join(outputDir, "types.d.ts");
-  fs7.writeFileSync(entryPath, entryContents, "utf8");
-  fs7.writeFileSync(typesPath, typesContents, "utf8");
+  fs8.writeFileSync(entryPath, entryContents, "utf8");
+  fs8.writeFileSync(typesPath, typesContents, "utf8");
   return {
     entryPath,
     typesPath
@@ -182,14 +502,18 @@ function renderEntryFile(discovery, workerEntryAbsolute, outDir, config) {
   const imports = [];
   const bindings = [];
   const queueMap = [];
-  imports.push(`import workerDefault, * as workerModule from '${toImportPath(outDir, workerEntryAbsolute)}';`);
+  imports.push(
+    `import workerDefault, * as workerModule from ${JSON.stringify(toImportPath(outDir, workerEntryAbsolute))};`
+  );
   imports.push(`import { getQueueInternals, resolveWorkerHandlers } from 'better-cf/queue/internal';`);
   for (const queue of discovery.queues) {
     const queueImportPath = toImportPath(outDir, queue.absoluteFilePath);
     if (queue.isDefaultExport) {
-      imports.push(`import ${queue.importName} from '${queueImportPath}';`);
+      imports.push(`import ${queue.importName} from ${JSON.stringify(queueImportPath)};`);
     } else {
-      imports.push(`import { ${queue.exportName} as ${queue.importName} } from '${queueImportPath}';`);
+      imports.push(
+        `import { ${queue.exportName} as ${queue.importName} } from ${JSON.stringify(queueImportPath)};`
+      );
     }
     bindings.push(`getQueueInternals(${queue.importName}).setBinding('${queue.bindingName}');`);
     queueMap.push(`  '${queue.queueName}': ${queue.importName}`);
@@ -246,6 +570,8 @@ declare module 'better-cf/queue' {
   interface BetterCfGeneratedBindings {
 ${lines.join("\n")}
   }
+
+  interface BetterCfAutoEnv extends BetterCfGeneratedBindings {}
 }
 
 export {};
@@ -260,10 +586,10 @@ function toImportPath(fromDir, targetFile) {
 }
 
 // src/cli/discovery/naming.ts
-function deriveQueueName(input) {
-  const withoutSuffix = input.replace(/Queue$/, "");
+function deriveQueueName(input2) {
+  const withoutSuffix = input2.replace(/Queue$/, "");
   const kebab = withoutSuffix.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
-  return kebab || input.toLowerCase();
+  return kebab || input2.toLowerCase();
 }
 function deriveBindingName(queueName) {
   return `QUEUE_${queueName.replace(/[^a-zA-Z0-9]/g, "_").replace(/_+/g, "_").toUpperCase()}`;
@@ -280,8 +606,10 @@ var RESERVED_KEYS = /* @__PURE__ */ new Set([
   "retry",
   "retryDelay",
   "deadLetter",
+  "deliveryDelay",
   "visibilityTimeout",
   "batch",
+  "consumer",
   "message",
   "process",
   "processBatch",
@@ -370,7 +698,7 @@ async function scanQueues(config) {
 }
 function createProject(rootDir) {
   const tsConfigPath = path3.join(rootDir, "tsconfig.json");
-  if (fs7.existsSync(tsConfigPath)) {
+  if (fs8.existsSync(tsConfigPath)) {
     return new Project({
       tsConfigFilePath: tsConfigPath,
       skipAddingFilesFromTsConfig: true
@@ -389,7 +717,7 @@ function collectSourceFiles(rootDir, ignore) {
   const files = [];
   const ignoreSet = new Set(ignore);
   function walk(currentPath) {
-    const entries = fs7.readdirSync(currentPath, { withFileTypes: true });
+    const entries = fs8.readdirSync(currentPath, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.name.startsWith(".git")) {
         continue;
@@ -403,7 +731,7 @@ function collectSourceFiles(rootDir, ignore) {
         continue;
       }
       if (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) {
-        const content = fs7.readFileSync(absolutePath, "utf8");
+        const content = fs8.readFileSync(absolutePath, "utf8");
         if (content.includes("defineQueue")) {
           files.push(absolutePath);
         }
@@ -467,7 +795,8 @@ function extractQueueConfig(call, absolutePath, diagnostics, rootDir) {
       level: "error",
       code: "INVALID_PROCESS_MODE",
       message: "Queue config cannot include both process and processBatch.",
-      filePath: path3.relative(rootDir, absolutePath)
+      filePath: path3.relative(rootDir, absolutePath),
+      hint: "Pick exactly one processing mode for worker consumers."
     });
   }
   const retry = readNumberProperty(objectLiteral, "retry", diagnostics, absolutePath, rootDir);
@@ -479,13 +808,23 @@ function extractQueueConfig(call, absolutePath, diagnostics, rootDir) {
     rootDir
   );
   const deadLetter = readStringProperty(objectLiteral, "deadLetter", diagnostics, absolutePath, rootDir);
-  const visibilityTimeout = readNumberOrStringProperty(
+  const deliveryDelay = readNumberOrStringProperty(
+    objectLiteral,
+    "deliveryDelay",
+    diagnostics,
+    absolutePath,
+    rootDir
+  );
+  const topLevelVisibilityTimeout = readNumberOrStringProperty(
     objectLiteral,
     "visibilityTimeout",
     diagnostics,
     absolutePath,
     rootDir
   );
+  const consumer = readConsumerConfig(objectLiteral, diagnostics, absolutePath, rootDir);
+  const consumerType = consumer?.type;
+  const visibilityTimeout = consumer?.visibilityTimeout ?? topLevelVisibilityTimeout;
   const batchObject = getObjectLiteralProperty(objectLiteral, "batch");
   const batchMaxSize = batchObject ? readNumberProperty(batchObject, "maxSize", diagnostics, absolutePath, rootDir) : void 0;
   const batchTimeout = batchObject ? readNumberOrStringProperty(batchObject, "timeout", diagnostics, absolutePath, rootDir) : void 0;
@@ -511,14 +850,35 @@ function extractQueueConfig(call, absolutePath, diagnostics, rootDir) {
       }
     }
   }
+  const relativeFile = path3.relative(rootDir, absolutePath);
+  if (consumerType === "http_pull" && (hasProcess || hasProcessBatch)) {
+    diagnostics.push({
+      level: "error",
+      code: "INVALID_PULL_MODE_HANDLER",
+      message: 'Queue with consumer.type="http_pull" cannot include process/processBatch.',
+      filePath: relativeFile,
+      hint: "Remove process handlers for pull consumers and consume via HTTP pull APIs."
+    });
+  }
+  if (consumerType === "http_pull" && isMultiJob) {
+    diagnostics.push({
+      level: "error",
+      code: "UNSUPPORTED_PULL_MULTIJOB",
+      message: 'Multi-job queue mode is not supported when consumer.type="http_pull".',
+      filePath: relativeFile,
+      hint: "Split jobs into separate queues when using http_pull."
+    });
+  }
   return {
     retry,
     retryDelay,
     deadLetter,
+    deliveryDelay,
     batchMaxSize,
     batchTimeout,
     maxConcurrency,
     visibilityTimeout,
+    consumerType,
     hasProcess,
     hasProcessBatch,
     isMultiJob
@@ -610,6 +970,36 @@ function readNumberOrStringProperty(objectLiteral, name, diagnostics, absolutePa
   });
   return void 0;
 }
+function readConsumerConfig(objectLiteral, diagnostics, absolutePath, rootDir) {
+  const consumerObject = getObjectLiteralProperty(objectLiteral, "consumer");
+  if (!consumerObject) {
+    return void 0;
+  }
+  const typeValue = readStringProperty(consumerObject, "type", diagnostics, absolutePath, rootDir);
+  if (!typeValue) {
+    return void 0;
+  }
+  if (typeValue !== "worker" && typeValue !== "http_pull") {
+    diagnostics.push({
+      level: "warning",
+      code: "NON_STATIC_CONFIG",
+      message: `Unknown consumer.type "${typeValue}" in ${path3.relative(rootDir, absolutePath)}.`,
+      filePath: path3.relative(rootDir, absolutePath)
+    });
+    return void 0;
+  }
+  const visibilityTimeout = readNumberOrStringProperty(
+    consumerObject,
+    "visibilityTimeout",
+    diagnostics,
+    absolutePath,
+    rootDir
+  );
+  return {
+    type: typeValue,
+    visibilityTimeout
+  };
+}
 function addConflictDiagnostics(queues, diagnostics) {
   const queueNameMap = /* @__PURE__ */ new Map();
   const bindingNameMap = /* @__PURE__ */ new Map();
@@ -647,8 +1037,105 @@ function toErrorMessage(value) {
   }
   return String(value);
 }
+var WRANGLER_ENV_INTERFACE = "BetterCfWranglerEnv";
+async function generateEnvTypes(config) {
+  const outDir = path3.join(config.rootDir, ".better-cf");
+  fs8.mkdirSync(outDir, { recursive: true });
+  const wranglerEnvPath = path3.join(outDir, "wrangler-env.d.ts");
+  const autoEnvPath = path3.join(outDir, "auto-env.d.ts");
+  const skipWrangler = process.env.BETTER_CF_SKIP_WRANGLER_TYPES === "1" || config.inferEnvTypes === false;
+  if (skipWrangler) {
+    fs8.writeFileSync(
+      wranglerEnvPath,
+      `// Auto-generated fallback when wrangler types is skipped.
+interface ${WRANGLER_ENV_INTERFACE} {
+  [key: string]: unknown;
+}
+`,
+      "utf8"
+    );
+  } else {
+    const command = await runCommandCapture(
+      "npx",
+      ["wrangler", "types", "--path", wranglerEnvPath, "--env-interface", WRANGLER_ENV_INTERFACE],
+      config.rootDir
+    );
+    if (command.code !== 0) {
+      throw new CliError({
+        code: "WRANGLER_TYPES_FAILED",
+        summary: "Failed to infer env types with wrangler.",
+        details: command.stderr || command.stdout || `Exit code ${command.code}`,
+        hint: "Install wrangler >=3.91 and verify wrangler config is valid.",
+        docsUrl: "https://developers.cloudflare.com/workers/wrangler/commands/#types"
+      });
+    }
+    if (!fs8.existsSync(wranglerEnvPath)) {
+      throw new CliError({
+        code: "WRANGLER_TYPES_OUTPUT_MISSING",
+        summary: "Wrangler types command succeeded but output file was not created.",
+        file: wranglerEnvPath,
+        hint: "Check wrangler CLI version and project permissions."
+      });
+    }
+  }
+  fs8.writeFileSync(
+    autoEnvPath,
+    `// Auto-generated by better-cf. Do not edit.
+/// <reference path="./wrangler-env.d.ts" />
+
+declare module 'better-cf/queue' {
+  interface BetterCfAutoEnv extends BetterCfGeneratedBindings, ${WRANGLER_ENV_INTERFACE} {}
+}
+
+export {};
+`,
+    "utf8"
+  );
+  return {
+    wranglerEnvPath,
+    autoEnvPath
+  };
+}
+
+// src/cli/wrangler/duration.ts
+function parseDurationSecondsStrict(value, context) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new CliError({
+        code: "INVALID_DURATION",
+        summary: `Invalid duration for ${context}.`,
+        details: `Expected non-negative finite number, received ${String(value)}.`,
+        hint: 'Use values like 30 or "30s", "5m", "1h".'
+      });
+    }
+    return value;
+  }
+  const match = value.match(/^(\d+)(s|m|h)$/);
+  if (!match) {
+    throw new CliError({
+      code: "INVALID_DURATION",
+      summary: `Invalid duration string for ${context}.`,
+      details: `Received "${value}".`,
+      hint: 'Use formats like "30s", "5m", "1h".'
+    });
+  }
+  const amount = Number.parseInt(match[1], 10);
+  const unit = match[2];
+  if (unit === "s") {
+    return amount;
+  }
+  if (unit === "m") {
+    return amount * 60;
+  }
+  return amount * 3600;
+}
+function parseDurationMsStrict(value, context) {
+  return parseDurationSecondsStrict(value, context) * 1e3;
+}
+
+// src/cli/wrangler/jsonc.ts
 function patchJsoncConfig(filePath, discovery) {
-  let text = fs7.readFileSync(filePath, "utf8");
+  let text = fs8.readFileSync(filePath, "utf8");
   text = applyEdits(
     text,
     modify(text, ["main"], ".better-cf/entry.ts", {
@@ -657,28 +1144,46 @@ function patchJsoncConfig(filePath, discovery) {
   );
   const producers = discovery.queues.map((queue) => ({
     queue: queue.queueName,
-    binding: queue.bindingName
-  }));
-  const consumers = discovery.queues.map((queue) => ({
-    queue: queue.queueName,
-    ...queue.config.batchMaxSize !== void 0 ? { max_batch_size: queue.config.batchMaxSize } : {},
-    ...queue.config.batchTimeout !== void 0 ? { max_batch_timeout: parseDurationSeconds(queue.config.batchTimeout) } : {},
-    ...queue.config.retry !== void 0 ? { max_retries: queue.config.retry } : {},
-    ...queue.config.deadLetter !== void 0 ? { dead_letter_queue: queue.config.deadLetter } : {},
-    ...queue.config.maxConcurrency !== void 0 ? { max_concurrency: queue.config.maxConcurrency } : {},
-    ...queue.config.retryDelay !== void 0 ? { retry_delay: parseDurationSeconds(queue.config.retryDelay) } : {}
+    binding: queue.bindingName,
+    ...queue.config.deliveryDelay !== void 0 ? { delivery_delay: parseDurationSecondsStrict(queue.config.deliveryDelay, `${queue.queueName}.deliveryDelay`) } : {}
   }));
+  const consumers = discovery.queues.map((queue) => {
+    const base = {
+      queue: queue.queueName,
+      ...queue.config.retry !== void 0 ? { max_retries: queue.config.retry } : {},
+      ...queue.config.deadLetter !== void 0 ? { dead_letter_queue: queue.config.deadLetter } : {},
+      ...queue.config.retryDelay !== void 0 ? { retry_delay: parseDurationSecondsStrict(queue.config.retryDelay, `${queue.queueName}.retryDelay`) } : {}
+    };
+    if (queue.config.consumerType === "http_pull") {
+      return {
+        ...base,
+        type: "http_pull",
+        ...queue.config.visibilityTimeout !== void 0 ? {
+          visibility_timeout_ms: parseDurationMsStrict(
+            queue.config.visibilityTimeout,
+            `${queue.queueName}.visibilityTimeout`
+          )
+        } : {}
+      };
+    }
+    return {
+      ...base,
+      ...queue.config.batchMaxSize !== void 0 ? { max_batch_size: queue.config.batchMaxSize } : {},
+      ...queue.config.batchTimeout !== void 0 ? { max_batch_timeout: parseDurationSecondsStrict(queue.config.batchTimeout, `${queue.queueName}.batch.timeout`) } : {},
+      ...queue.config.maxConcurrency !== void 0 ? { max_concurrency: queue.config.maxConcurrency } : {}
+    };
+  });
   text = applyEdits(
     text,
     modify(text, ["queues"], { producers, consumers, better_cf_managed: true }, {
       formattingOptions: { insertSpaces: true, tabSize: 2 }
     })
   );
-  fs7.writeFileSync(filePath, text, "utf8");
+  fs8.writeFileSync(filePath, text, "utf8");
 }
 function ensureJsoncExists(rootDir) {
   const filePath = path3.join(rootDir, "wrangler.jsonc");
-  if (!fs7.existsSync(filePath)) {
+  if (!fs8.existsSync(filePath)) {
     const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const content = `{
   "$schema": "node_modules/wrangler/config-schema.json",
@@ -691,37 +1196,19 @@ function ensureJsoncExists(rootDir) {
   }
 }
 `;
-    fs7.writeFileSync(filePath, content, "utf8");
+    fs8.writeFileSync(filePath, content, "utf8");
   } else {
-    const parsed = parse(fs7.readFileSync(filePath, "utf8"));
+    const parsed = parse(fs8.readFileSync(filePath, "utf8"));
     if (!parsed.queues) {
       patchJsoncConfig(filePath, { queues: []});
     }
   }
   return filePath;
 }
-function parseDurationSeconds(value) {
-  if (typeof value === "number") {
-    return value;
-  }
-  const match = value.match(/^(\d+)(s|m|h)$/);
-  if (!match) {
-    return Number(value) || 0;
-  }
-  const amount = Number.parseInt(match[1], 10);
-  const unit = match[2];
-  if (unit === "s") {
-    return amount;
-  }
-  if (unit === "m") {
-    return amount * 60;
-  }
-  return amount * 3600;
-}
 var START_MARKER = "# --- better-cf:start ---";
 var END_MARKER = "# --- better-cf:end ---";
 function patchTomlConfig(filePath, discovery) {
-  let content = fs7.readFileSync(filePath, "utf8");
+  let content = fs8.readFileSync(filePath, "utf8");
   content = ensureMainEntry(content);
   const generatedSection = renderQueueSection(discovery);
   const startIndex = content.indexOf(START_MARKER);
@@ -740,11 +1227,11 @@ ${generatedSection}
 ${END_MARKER}
 `;
   }
-  fs7.writeFileSync(filePath, content, "utf8");
+  fs8.writeFileSync(filePath, content, "utf8");
 }
 function ensureTomlExists(rootDir) {
   const filePath = path3.join(rootDir, "wrangler.toml");
-  if (!fs7.existsSync(filePath)) {
+  if (!fs8.existsSync(filePath)) {
     const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const initial = `name = "my-worker"
 main = ".better-cf/entry.ts"
@@ -753,7 +1240,7 @@ compatibility_date = "${date}"
 ${START_MARKER}
 ${END_MARKER}
 `;
-    fs7.writeFileSync(filePath, initial, "utf8");
+    fs8.writeFileSync(filePath, initial, "utf8");
   }
   return filePath;
 }
@@ -768,50 +1255,62 @@ function renderQueueSection(discovery) {
   const lines = [];
   for (const queue of discovery.queues) {
     lines.push("[[queues.producers]]");
-    lines.push(`queue = "${queue.queueName}"`);
-    lines.push(`binding = "${queue.bindingName}"`);
+    lines.push(`queue = ${toTomlString(queue.queueName)}`);
+    lines.push(`binding = ${toTomlString(queue.bindingName)}`);
+    if (queue.config.deliveryDelay !== void 0) {
+      lines.push(
+        `delivery_delay = ${parseDurationSecondsStrict(
+          queue.config.deliveryDelay,
+          `${queue.queueName}.deliveryDelay`
+        )}`
+      );
+    }
     lines.push("");
     lines.push("[[queues.consumers]]");
-    lines.push(`queue = "${queue.queueName}"`);
-    if (queue.config.batchMaxSize !== void 0) {
-      lines.push(`max_batch_size = ${queue.config.batchMaxSize}`);
-    }
-    if (queue.config.batchTimeout !== void 0) {
-      lines.push(`max_batch_timeout = ${parseDurationSeconds2(queue.config.batchTimeout)}`);
+    lines.push(`queue = ${toTomlString(queue.queueName)}`);
+    if (queue.config.consumerType === "http_pull") {
+      lines.push(`type = ${toTomlString("http_pull")}`);
+      if (queue.config.visibilityTimeout !== void 0) {
+        lines.push(
+          `visibility_timeout_ms = ${parseDurationMsStrict(
+            queue.config.visibilityTimeout,
+            `${queue.queueName}.visibilityTimeout`
+          )}`
+        );
+      }
+    } else {
+      if (queue.config.batchMaxSize !== void 0) {
+        lines.push(`max_batch_size = ${queue.config.batchMaxSize}`);
+      }
+      if (queue.config.batchTimeout !== void 0) {
+        lines.push(
+          `max_batch_timeout = ${parseDurationSecondsStrict(
+            queue.config.batchTimeout,
+            `${queue.queueName}.batch.timeout`
+          )}`
+        );
+      }
+      if (queue.config.maxConcurrency !== void 0) {
+        lines.push(`max_concurrency = ${queue.config.maxConcurrency}`);
+      }
     }
     if (queue.config.retry !== void 0) {
       lines.push(`max_retries = ${queue.config.retry}`);
     }
     if (queue.config.deadLetter !== void 0) {
-      lines.push(`dead_letter_queue = "${queue.config.deadLetter}"`);
-    }
-    if (queue.config.maxConcurrency !== void 0) {
-      lines.push(`max_concurrency = ${queue.config.maxConcurrency}`);
+      lines.push(`dead_letter_queue = ${toTomlString(queue.config.deadLetter)}`);
     }
     if (queue.config.retryDelay !== void 0) {
-      lines.push(`retry_delay = ${parseDurationSeconds2(queue.config.retryDelay)}`);
+      lines.push(
+        `retry_delay = ${parseDurationSecondsStrict(queue.config.retryDelay, `${queue.queueName}.retryDelay`)}`
+      );
     }
     lines.push("");
   }
   return lines.join("\n").trimEnd();
 }
-function parseDurationSeconds2(value) {
-  if (typeof value === "number") {
-    return value;
-  }
-  const match = value.match(/^(\d+)(s|m|h)$/);
-  if (!match) {
-    return Number(value) || 0;
-  }
-  const amount = Number.parseInt(match[1], 10);
-  const unit = match[2];
-  if (unit === "s") {
-    return amount;
-  }
-  if (unit === "m") {
-    return amount * 60;
-  }
-  return amount * 3600;
+function toTomlString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
 }
 
 // src/cli/wrangler/index.ts
@@ -833,11 +1332,11 @@ function detectWranglerConfig(rootDir) {
   const preferred = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
   for (const fileName of preferred) {
     const absolutePath = path3.join(rootDir, fileName);
-    if (fs7.existsSync(absolutePath)) {
+    if (fs8.existsSync(absolutePath)) {
       return absolutePath;
     }
   }
-  if (fs7.existsSync(path3.join(rootDir, "package.json")) && fs7.existsSync(path3.join(rootDir, "src"))) {
+  if (fs8.existsSync(path3.join(rootDir, "package.json")) && fs8.existsSync(path3.join(rootDir, "src"))) {
     return ensureJsoncExists(rootDir);
   }
   return void 0;
@@ -848,23 +1347,26 @@ async function runGenerate(rootDir = process.cwd()) {
   const config = loadCliConfig(rootDir);
   const discovery = await scanQueues(config);
   for (const diagnostic of discovery.diagnostics) {
-    if (diagnostic.level === "error") {
-      logger.error(diagnostic.message);
-    } else {
-      logger.warn(diagnostic.message);
-    }
+    logger.diagnostic(diagnostic);
   }
   const hasErrors = discovery.diagnostics.some((diag) => diag.level === "error");
   if (hasErrors) {
-    throw new Error("Queue discovery failed due to configuration errors.");
+    throw new CliError({
+      code: "QUEUE_DISCOVERY_FAILED",
+      summary: "Queue discovery failed due to configuration errors.",
+      hint: "Fix the diagnostics above and re-run `better-cf generate`.",
+      docsUrl: "https://github.com/better-cf/better-cf#errors"
+    });
   }
   const generated = generateCode(discovery, config);
   const wranglerConfigPath = patchWranglerConfig(config, discovery);
+  const envTypeResult = await generateEnvTypes(config);
   return {
     discovery,
     generatedEntryPath: generated.entryPath,
     generatedTypesPath: generated.typesPath,
-    wranglerConfigPath
+    wranglerConfigPath,
+    autoEnvPath: envTypeResult.autoEnvPath
   };
 }
 async function generateCommand(rootDir = process.cwd()) {
@@ -872,6 +1374,7 @@ async function generateCommand(rootDir = process.cwd()) {
   logger.success(`Generated ${result.discovery.queues.length} queue(s)`);
   logger.item("entry", result.generatedEntryPath);
   logger.item("types", result.generatedTypesPath);
+  logger.item("auto-env", result.autoEnvPath);
   logger.item("wrangler", result.wranglerConfigPath);
 }
 
@@ -881,7 +1384,12 @@ async function deployCommand(rootDir = process.cwd()) {
   logger.section("Deploying with wrangler");
   const code = await runCommand("npx", ["wrangler", "deploy"], rootDir, "inherit");
   if (code !== 0) {
-    throw new Error(`wrangler deploy failed with code ${code}`);
+    throw new CliError({
+      code: "WRANGLER_DEPLOY_FAILED",
+      summary: "wrangler deploy failed.",
+      details: `wrangler exited with code ${code}`,
+      hint: "Run wrangler deploy manually to inspect environment-specific failures."
+    });
   }
   logger.success("Deployment complete");
   logger.section("Active queue bindings");
@@ -889,28 +1397,48 @@ async function deployCommand(rootDir = process.cwd()) {
     logger.item(queue.queueName, queue.bindingName);
   }
 }
+var WATCH_GLOBS = [
+  "**/*.ts",
+  "**/*.tsx",
+  "better-cf.config.ts",
+  "wrangler.toml",
+  "wrangler.json",
+  "wrangler.jsonc",
+  "tsconfig.json"
+];
 function createProjectWatcher(rootDir, options) {
-  const watcher = chokidar.watch(["**/*.ts", "**/*.tsx"], {
+  const watcher = chokidar.watch(WATCH_GLOBS, {
     cwd: rootDir,
     ignored: options.ignored.map((entry) => `${entry}/**`),
-    ignoreInitial: true
+    ignoreInitial: true,
+    usePolling: true,
+    interval: 100,
+    awaitWriteFinish: {
+      stabilityThreshold: 150,
+      pollInterval: 25
+    }
   });
   const handler = async (filePath) => {
-    if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx")) {
-      return;
-    }
     await options.onRelevantChange(filePath);
   };
   watcher.on("add", handler);
   watcher.on("change", handler);
   watcher.on("unlink", handler);
+  watcher.on("ready", () => {
+    void options.onRelevantChange("__watcher_ready__");
+  });
   return watcher;
 }
 
 // src/cli/commands/dev.ts
 async function devCommand(options, rootDir = process.cwd()) {
   if (options.remote) {
-    throw new Error("Cloudflare Queues do not support wrangler dev --remote. Use local mode only.");
+    throw new CliError({
+      code: "REMOTE_QUEUE_DEV_UNSUPPORTED",
+      summary: "Cloudflare Queues do not support wrangler dev --remote.",
+      hint: "Run better-cf dev without --remote for queue consumer development.",
+      docsUrl: "https://developers.cloudflare.com/queues/configuration/local-development/"
+    });
   }
   let wranglerProcess = null;
   let isRebuilding = false;
@@ -936,7 +1464,8 @@ async function devCommand(options, rootDir = process.cwd()) {
   await buildAndRestart("initial build");
   if (options.watch) {
     const watcher = createProjectWatcher(rootDir, {
-      ignored: ["node_modules", ".better-cf", "dist"],
+      // Ignore Wrangler's local build output to avoid self-triggered rebuild loops.
+      ignored: ["node_modules", ".better-cf", ".wrangler", "dist"],
       onRelevantChange: async (filePath) => {
         await buildAndRestart(`file changed: ${filePath}`);
       }
@@ -955,46 +1484,53 @@ async function devCommand(options, rootDir = process.cwd()) {
 }
 async function initCommand(rootDir = process.cwd()) {
   const configPath = path3.join(rootDir, "better-cf.config.ts");
-  if (!fs7.existsSync(configPath)) {
-    fs7.writeFileSync(configPath, defaultConfigTemplate(), "utf8");
+  if (!fs8.existsSync(configPath)) {
+    fs8.writeFileSync(configPath, defaultConfigTemplate(), "utf8");
     logger.success("Created better-cf.config.ts");
   }
   const workerPath = path3.join(rootDir, "worker.ts");
   const srcWorkerPath = path3.join(rootDir, "src", "worker.ts");
-  if (!fs7.existsSync(workerPath) && !fs7.existsSync(srcWorkerPath)) {
-    fs7.writeFileSync(workerPath, defaultWorkerTemplate(), "utf8");
+  if (!fs8.existsSync(workerPath) && !fs8.existsSync(srcWorkerPath)) {
+    fs8.writeFileSync(workerPath, defaultWorkerTemplate(), "utf8");
     logger.success("Created worker.ts");
   }
   const outputDir = path3.join(rootDir, ".better-cf");
-  fs7.mkdirSync(outputDir, { recursive: true });
+  fs8.mkdirSync(outputDir, { recursive: true });
   const gitignorePath = path3.join(rootDir, ".gitignore");
-  if (!fs7.existsSync(gitignorePath)) {
-    fs7.writeFileSync(gitignorePath, ".better-cf/\nnode_modules/\n", "utf8");
+  if (!fs8.existsSync(gitignorePath)) {
+    fs8.writeFileSync(gitignorePath, ".better-cf/\nnode_modules/\n", "utf8");
     logger.success("Created .gitignore");
   } else {
-    const existing = fs7.readFileSync(gitignorePath, "utf8");
+    const existing = fs8.readFileSync(gitignorePath, "utf8");
     if (!existing.includes(".better-cf/")) {
-      fs7.appendFileSync(gitignorePath, "\n.better-cf/\n", "utf8");
+      fs8.appendFileSync(gitignorePath, "\n.better-cf/\n", "utf8");
       logger.success("Updated .gitignore");
     }
   }
   const packageJsonPath = path3.join(rootDir, "package.json");
-  if (fs7.existsSync(packageJsonPath)) {
-    const packageJson = JSON.parse(fs7.readFileSync(packageJsonPath, "utf8"));
-    packageJson.scripts = packageJson.scripts ?? {};
-    packageJson.scripts.dev = packageJson.scripts.dev ?? "better-cf dev";
-    packageJson.scripts.deploy = packageJson.scripts.deploy ?? "better-cf deploy";
-    packageJson.scripts.generate = "better-cf generate";
-    fs7.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}
+  const packageJsonExists = fs8.existsSync(packageJsonPath);
+  const packageJson = packageJsonExists ? JSON.parse(fs8.readFileSync(packageJsonPath, "utf8")) : {
+    name: derivePackageName(rootDir),
+    version: "0.0.0",
+    private: true,
+    scripts: {}
+  };
+  if (!packageJsonExists) {
+    logger.success("Created package.json");
+  }
+  packageJson.scripts = packageJson.scripts ?? {};
+  packageJson.scripts.dev = packageJson.scripts.dev ?? "better-cf dev";
+  packageJson.scripts.deploy = packageJson.scripts.deploy ?? "better-cf deploy";
+  packageJson.scripts.generate = "better-cf generate";
+  fs8.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}
 `, "utf8");
-    logger.success("Updated package.json scripts");
-  }
+  logger.success("Updated package.json scripts");
   const wranglerTomlPath = path3.join(rootDir, "wrangler.toml");
   const wranglerJsoncPath = path3.join(rootDir, "wrangler.jsonc");
   const wranglerJsonPath = path3.join(rootDir, "wrangler.json");
-  if (!fs7.existsSync(wranglerTomlPath) && !fs7.existsSync(wranglerJsoncPath) && !fs7.existsSync(wranglerJsonPath)) {
+  if (!fs8.existsSync(wranglerTomlPath) && !fs8.existsSync(wranglerJsoncPath) && !fs8.existsSync(wranglerJsonPath)) {
     const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-    fs7.writeFileSync(
+    fs8.writeFileSync(
       wranglerTomlPath,
       `name = "my-worker"
 main = ".better-cf/entry.ts"
@@ -1009,19 +1545,23 @@ compatibility_date = "${date}"
   }
   logger.info("Next steps: create a queue export and run `better-cf dev`.");
 }
+function derivePackageName(rootDir) {
+  const raw = path3.basename(path3.resolve(rootDir)).toLowerCase().trim();
+  const normalized = raw.replace(/[^a-z0-9._-]+/g, "-").replace(/^-+/, "").replace(/-+$/, "");
+  return normalized || "better-cf-app";
+}
 function defaultConfigTemplate() {
   return `import { createSDK } from 'better-cf/queue';
 
-export type Env = {
-  // DB: D1Database;
-};
-
-export const { defineQueue, defineWorker } = createSDK<Env>();
+// Auto-inferred env types are generated under .better-cf/*.d.ts
+// You can still switch to createSDK<Env>() when you need explicit overrides.
+export const { defineQueue, defineWorker } = createSDK();
 
 export const betterCfConfig = {
   // workerEntry: 'worker.ts',
   // ignore: ['coverage'],
   legacyServiceWorker: false,
+  inferEnvTypes: true,
 };
 `;
 }
@@ -1035,11 +1575,231 @@ export default defineWorker({
 });
 `;
 }
+var DEFAULT_PROJECT_DIR = "better-cf-app";
+var PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
+var INSTALL_PLANS = {
+  npm: {
+    command: "npm",
+    runtimeArgs: ["install", "better-cf", "zod"],
+    devArgs: ["install", "-D", "wrangler", "@cloudflare/workers-types", "typescript"],
+    devRunCommand: "npm run dev"
+  },
+  pnpm: {
+    command: "pnpm",
+    runtimeArgs: ["add", "better-cf", "zod"],
+    devArgs: ["add", "-D", "wrangler", "@cloudflare/workers-types", "typescript"],
+    devRunCommand: "pnpm dev"
+  },
+  yarn: {
+    command: "yarn",
+    runtimeArgs: ["add", "better-cf", "zod"],
+    devArgs: ["add", "-D", "wrangler", "@cloudflare/workers-types", "typescript"],
+    devRunCommand: "yarn dev"
+  },
+  bun: {
+    command: "bun",
+    runtimeArgs: ["add", "better-cf", "zod"],
+    devArgs: ["add", "-d", "wrangler", "@cloudflare/workers-types", "typescript"],
+    devRunCommand: "bun run dev"
+  }
+};
+async function createCommand(projectDirectoryArg, options = {}, rootDir = process.cwd()) {
+  const isYes = options.yes ?? false;
+  const shouldInstallByDefault = options.install ?? true;
+  const isInteractive = Boolean(stdin.isTTY && stdout.isTTY && !isYes);
+  const prompts = isInteractive ? createPrompts() : void 0;
+  try {
+    const projectDirectory = await resolveProjectDirectory(projectDirectoryArg, isYes, prompts);
+    const targetDir = path3.resolve(rootDir, projectDirectory);
+    ensureTargetDirectory(targetDir, options.force ?? false);
+    await initCommand(targetDir);
+    const detectedPackageManager = detectPackageManager(rootDir);
+    const packageManager = options.packageManager ?? (prompts ? await prompts.selectPackageManager(detectedPackageManager) : detectedPackageManager);
+    const shouldInstall = shouldInstallByDefault && (prompts ? await prompts.confirmInstall(true) : true);
+    if (shouldInstall) {
+      await installDependencies(packageManager, targetDir);
+    }
+    const relativePath = path3.relative(rootDir, targetDir) || ".";
+    const plan = INSTALL_PLANS[packageManager];
+    logger.section("Project ready");
+    logger.item("path", targetDir);
+    if (relativePath !== ".") {
+      logger.item("cd", `cd ${relativePath}`);
+    }
+    if (!shouldInstall) {
+      logger.item("install", `${plan.command} ${plan.runtimeArgs.join(" ")}`);
+      logger.item("install (dev)", `${plan.command} ${plan.devArgs.join(" ")}`);
+    }
+    logger.item("dev", plan.devRunCommand);
+  } finally {
+    prompts?.close();
+  }
+}
+function detectPackageManager(rootDir = process.cwd()) {
+  if (fs8.existsSync(path3.join(rootDir, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (fs8.existsSync(path3.join(rootDir, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (fs8.existsSync(path3.join(rootDir, "bun.lock")) || fs8.existsSync(path3.join(rootDir, "bun.lockb"))) {
+    return "bun";
+  }
+  const userAgent = process.env.npm_config_user_agent?.toLowerCase() ?? "";
+  if (userAgent.startsWith("pnpm")) {
+    return "pnpm";
+  }
+  if (userAgent.startsWith("yarn")) {
+    return "yarn";
+  }
+  if (userAgent.startsWith("bun")) {
+    return "bun";
+  }
+  if (userAgent.startsWith("npm")) {
+    return "npm";
+  }
+  return "npm";
+}
+function ensureTargetDirectory(targetDir, force) {
+  if (!fs8.existsSync(targetDir)) {
+    fs8.mkdirSync(targetDir, { recursive: true });
+    return;
+  }
+  const stats = fs8.statSync(targetDir);
+  if (!stats.isDirectory()) {
+    throw new CliError({
+      code: "CREATE_TARGET_INVALID",
+      summary: `Target path exists and is not a directory: ${targetDir}.`,
+      hint: "Choose a different project directory."
+    });
+  }
+  const contents = fs8.readdirSync(targetDir).filter((entry) => entry !== ".DS_Store");
+  if (contents.length > 0 && !force) {
+    throw new CliError({
+      code: "CREATE_TARGET_NOT_EMPTY",
+      summary: `Target directory is not empty: ${targetDir}.`,
+      hint: "Use --force to scaffold in a non-empty directory."
+    });
+  }
+}
+async function resolveProjectDirectory(projectDirectoryArg, isYes, prompts) {
+  if (projectDirectoryArg && projectDirectoryArg.trim().length > 0) {
+    return projectDirectoryArg.trim();
+  }
+  if (isYes) {
+    return DEFAULT_PROJECT_DIR;
+  }
+  if (!prompts) {
+    throw new CliError({
+      code: "CREATE_TARGET_REQUIRED",
+      summary: "Project directory is required in non-interactive mode.",
+      hint: "Pass a directory name, for example: `better-cf create my-worker`."
+    });
+  }
+  return prompts.askProjectDirectory(DEFAULT_PROJECT_DIR);
+}
+async function installDependencies(packageManager, targetDir) {
+  const plan = INSTALL_PLANS[packageManager];
+  logger.section(`Installing dependencies with ${plan.command}`);
+  await runInstallCommand(plan.command, plan.runtimeArgs, targetDir);
+  await runInstallCommand(plan.command, plan.devArgs, targetDir);
+}
+async function runInstallCommand(command, args, cwd) {
+  try {
+    const code = await runCommand(command, args, cwd, "inherit");
+    if (code !== 0) {
+      throw new CliError({
+        code: "DEPENDENCY_INSTALL_FAILED",
+        summary: `Dependency install failed: ${command} ${args.join(" ")}`,
+        details: `Command exited with code ${code}.`,
+        hint: `Run this command manually in ${cwd}.`
+      });
+    }
+  } catch (error) {
+    if (error instanceof CliError) {
+      throw error;
+    }
+    throw new CliError({
+      code: "DEPENDENCY_INSTALL_FAILED",
+      summary: `Dependency install failed: ${command} ${args.join(" ")}`,
+      details: error instanceof Error ? error.message : String(error),
+      hint: `Install dependencies manually in ${cwd}.`
+    });
+  }
+}
+function createPrompts() {
+  const rl = createInterface({ input: stdin, output: stdout });
+  return {
+    async askProjectDirectory(defaultValue) {
+      while (true) {
+        const raw = await rl.question(`Project directory (${defaultValue}): `);
+        const value = raw.trim() || defaultValue;
+        if (value.length > 0) {
+          return value;
+        }
+      }
+    },
+    async selectPackageManager(defaultValue) {
+      const defaultIndex = PACKAGE_MANAGERS.indexOf(defaultValue);
+      while (true) {
+        stdout.write("\nSelect a package manager:\n");
+        PACKAGE_MANAGERS.forEach((manager, index) => {
+          stdout.write(`  ${index + 1}) ${manager}${manager === defaultValue ? " (default)" : ""}
+`);
+        });
+        const raw = await rl.question(`Package manager [${defaultIndex + 1}]: `);
+        const normalized = raw.trim().toLowerCase();
+        if (!normalized) {
+          return defaultValue;
+        }
+        if (PACKAGE_MANAGERS.includes(normalized)) {
+          return normalized;
+        }
+        const asNumber = Number(normalized);
+        if (Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= PACKAGE_MANAGERS.length) {
+          return PACKAGE_MANAGERS[asNumber - 1];
+        }
+        logger.warn(`Unsupported package manager input: ${raw}`);
+      }
+    },
+    async confirmInstall(defaultValue) {
+      const hint = defaultValue ? "Y/n" : "y/N";
+      while (true) {
+        const raw = await rl.question(`Install dependencies now? (${hint}): `);
+        const normalized = raw.trim().toLowerCase();
+        if (!normalized) {
+          return defaultValue;
+        }
+        if (normalized === "y" || normalized === "yes") {
+          return true;
+        }
+        if (normalized === "n" || normalized === "no") {
+          return false;
+        }
+        logger.warn(`Unsupported confirmation input: ${raw}`);
+      }
+    },
+    close() {
+      rl.close();
+    }
+  };
+}
 
 // src/cli/index.ts
 async function run(argv = process.argv.slice(2)) {
   const program = new Command();
-  program.name("better-cf").description("better-cf queue SDK CLI").version("0.1.0");
+  program.name("better-cf").description("better-cf queue SDK CLI").version("0.2.1");
+  program.command("create [project-directory]").description("Create a new better-cf project").option("-y, --yes", "Use defaults and skip prompts").option("--no-install", "Skip dependency installation").option("--force", "Allow creating in a non-empty directory").option("--use-npm", "Use npm to install dependencies").option("--use-pnpm", "Use pnpm to install dependencies").option("--use-yarn", "Use yarn to install dependencies").option("--use-bun", "Use bun to install dependencies").action(
+    async (projectDirectory, options) => {
+      const packageManager = resolveCreatePackageManager(options);
+      await createCommand(projectDirectory, {
+        yes: options.yes,
+        install: options.install,
+        force: options.force,
+        packageManager
+      });
+    }
+  );
   program.command("init").description("Initialize better-cf in the current project").action(async () => {
     await initCommand();
   });
@@ -1052,13 +1812,181 @@ async function run(argv = process.argv.slice(2)) {
   program.command("deploy").description("Generate and deploy via wrangler deploy").action(async () => {
     await deployCommand();
   });
+  program.command("queue:list").description("List queues").action(async () => {
+    await queueListCommand();
+  });
+  program.command("queue:create").description("Create a queue").requiredOption("--name <name>", "Queue name").option("--delivery-delay-secs <seconds>", "Default delivery delay in seconds", parseNumberOption).option(
+    "--message-retention-period-secs <seconds>",
+    "Message retention period in seconds",
+    parseNumberOption
+  ).action(
+    async (options) => {
+      await queueCreateCommand(options.name, {
+        deliveryDelaySecs: options.deliveryDelaySecs,
+        messageRetentionPeriodSecs: options.messageRetentionPeriodSecs
+      });
+    }
+  );
+  program.command("queue:update").description("Update a queue").requiredOption("--name <name>", "Queue name").option("--delivery-delay-secs <seconds>", "Default delivery delay in seconds", parseNumberOption).option(
+    "--message-retention-period-secs <seconds>",
+    "Message retention period in seconds",
+    parseNumberOption
+  ).action(
+    async (options) => {
+      await queueUpdateCommand(options.name, {
+        deliveryDelaySecs: options.deliveryDelaySecs,
+        messageRetentionPeriodSecs: options.messageRetentionPeriodSecs
+      });
+    }
+  );
+  program.command("queue:delete").description("Delete a queue").requiredOption("--name <name>", "Queue name").action(async (options) => {
+    await queueDeleteCommand(options.name);
+  });
+  program.command("queue:info").description("Describe a queue").requiredOption("--name <name>", "Queue name").action(async (options) => {
+    await queueInfoCommand(options.name);
+  });
+  program.command("queue:pause").description("Pause queue delivery").requiredOption("--name <name>", "Queue name").action(async (options) => {
+    await queuePauseCommand(options.name);
+  });
+  program.command("queue:resume").description("Resume queue delivery").requiredOption("--name <name>", "Queue name").action(async (options) => {
+    await queueResumeCommand(options.name);
+  });
+  program.command("queue:purge").description("Purge queue messages").requiredOption("--name <name>", "Queue name").action(async (options) => {
+    await queuePurgeCommand(options.name);
+  });
+  program.command("queue:consumer:http:add").description("Add HTTP pull consumer for a queue").requiredOption("--queue <queue>", "Queue name").option("--batch-size <size>", "Batch size", parseNumberOption).option("--message-retries <retries>", "Message retries", parseNumberOption).option("--dead-letter-queue <queue>", "Dead letter queue name").option("--visibility-timeout-secs <seconds>", "Visibility timeout for pull consumer", parseNumberOption).option("--retry-delay-secs <seconds>", "Retry delay in seconds", parseNumberOption).action(
+    async (options) => {
+      await queueConsumerHttpAddCommand(options.queue, {
+        batchSize: options.batchSize,
+        messageRetries: options.messageRetries,
+        deadLetterQueue: options.deadLetterQueue,
+        visibilityTimeoutSecs: options.visibilityTimeoutSecs,
+        retryDelaySecs: options.retryDelaySecs
+      });
+    }
+  );
+  program.command("queue:consumer:http:remove").description("Remove HTTP pull consumer for a queue").requiredOption("--queue <queue>", "Queue name").action(async (options) => {
+    await queueConsumerHttpRemoveCommand(options.queue);
+  });
+  program.command("queue:consumer:worker:add").description("Add worker consumer for a queue").requiredOption("--queue <queue>", "Queue name").requiredOption("--script <script>", "Worker script name").option("--batch-size <size>", "Batch size", parseNumberOption).option("--batch-timeout <seconds>", "Batch timeout in seconds", parseNumberOption).option("--message-retries <retries>", "Message retries", parseNumberOption).option("--dead-letter-queue <queue>", "Dead letter queue name").option("--max-concurrency <count>", "Max consumer concurrency", parseNumberOption).option("--retry-delay-secs <seconds>", "Retry delay in seconds", parseNumberOption).action(
+    async (options) => {
+      await queueConsumerWorkerAddCommand(
+        options.queue,
+        options.script,
+        {
+          batchSize: options.batchSize,
+          batchTimeout: options.batchTimeout,
+          messageRetries: options.messageRetries,
+          deadLetterQueue: options.deadLetterQueue,
+          maxConcurrency: options.maxConcurrency,
+          retryDelaySecs: options.retryDelaySecs
+        }
+      );
+    }
+  );
+  program.command("queue:consumer:worker:remove").description("Remove worker consumer for a queue").requiredOption("--queue <queue>", "Queue name").requiredOption("--script <script>", "Worker script name").action(async (options) => {
+    await queueConsumerWorkerRemoveCommand(options.queue, options.script);
+  });
+  program.command("subscription:list").description("List queue subscriptions").requiredOption("--queue <queue>", "Queue name").option("--page <page>", "Page number", parseNumberOption).option("--per-page <count>", "Results per page", parseNumberOption).option("--json", "JSON output").action(async (options) => {
+    await subscriptionListCommand(
+      options.queue,
+      { page: options.page, perPage: options.perPage, json: options.json }
+    );
+  });
+  program.command("subscription:create").description("Create queue subscription").requiredOption("--queue <queue>", "Queue name").requiredOption("--source <source>", "Source id (same as queue name in most setups)").requiredOption("--events <events>", 'Event list (for example "message.acked")').option("--name <name>", "Subscription name").option("--enabled <enabled>", "Subscription enabled state (true/false)", parseBooleanOption).option("--model-name <modelName>", "AI model name (for AI gateway subscriptions)").option("--worker-name <workerName>", "Worker destination name").option("--workflow-name <workflowName>", "Workflow destination name").action(
+    async (options) => {
+      await subscriptionCreateCommand(options.queue, {
+        source: options.source,
+        events: options.events,
+        name: options.name,
+        enabled: options.enabled,
+        modelName: options.modelName,
+        workerName: options.workerName,
+        workflowName: options.workflowName
+      });
+    }
+  );
+  program.command("subscription:get").description("Get queue subscription").requiredOption("--queue <queue>", "Queue name").requiredOption("--id <id>", "Subscription ID").option("--json", "JSON output").action(async (options) => {
+    await subscriptionGetCommand(options.queue, options.id, { json: options.json });
+  });
+  program.command("subscription:update").description("Update queue subscription destination").requiredOption("--queue <queue>", "Queue name").requiredOption("--id <id>", "Subscription ID").option("--name <name>", "Subscription name").option("--events <events>", "Event list").option("--enabled <enabled>", "Subscription enabled state (true/false)", parseBooleanOption).option("--json", "JSON output").action(
+    async (options) => {
+      await subscriptionUpdateCommand(options.queue, options.id, {
+        name: options.name,
+        events: options.events,
+        enabled: options.enabled,
+        json: options.json
+      });
+    }
+  );
+  program.command("subscription:delete").description("Delete queue subscription").requiredOption("--queue <queue>", "Queue name").requiredOption("--id <id>", "Subscription ID").option("--force", "Skip confirmation where supported").action(async (options) => {
+    await subscriptionDeleteCommand(options.queue, options.id, { force: options.force });
+  });
   try {
     await program.parseAsync(argv, { from: "user" });
   } catch (error) {
-    logger.error(error instanceof Error ? error.message : String(error));
+    const cliError = toCliError(error);
+    logger.cliError({
+      code: cliError.code,
+      summary: cliError.summary,
+      file: cliError.file,
+      details: cliError.details,
+      hint: cliError.hint,
+      docsUrl: cliError.docsUrl
+    });
     process.exitCode = 1;
   }
 }
+function parseNumberOption(value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new CliError({
+      code: "INVALID_CLI_OPTION",
+      summary: `Invalid numeric option: ${value}.`,
+      details: "Expected a non-negative integer.",
+      hint: "Use values like 0, 1, 30, 120."
+    });
+  }
+  return parsed;
+}
+function parseBooleanOption(value) {
+  const normalized = value.toLowerCase();
+  if (normalized === "true") {
+    return true;
+  }
+  if (normalized === "false") {
+    return false;
+  }
+  throw new CliError({
+    code: "INVALID_CLI_OPTION",
+    summary: `Invalid boolean option: ${value}.`,
+    details: "Expected true or false.",
+    hint: "Use --enabled true or --enabled false."
+  });
+}
+function resolveCreatePackageManager(options) {
+  const selected = [];
+  if (options.useNpm) {
+    selected.push("npm");
+  }
+  if (options.usePnpm) {
+    selected.push("pnpm");
+  }
+  if (options.useYarn) {
+    selected.push("yarn");
+  }
+  if (options.useBun) {
+    selected.push("bun");
+  }
+  if (selected.length > 1) {
+    throw new CliError({
+      code: "INVALID_CLI_OPTION",
+      summary: "Conflicting package manager flags.",
+      details: "Use only one of --use-npm, --use-pnpm, --use-yarn, or --use-bun."
+    });
+  }
+  return selected[0];
+}
 
 export { run };
 //# sourceMappingURL=index.js.map