devflare 1.0.0-next.20 → 1.0.0-next.21

package/LLM.md

@@ -1278,12 +1278,12 @@ bunx --bun devflare productions rollback --help
 | Command | Primary job | What the deeper help covers |
 | --- | --- | --- |
 | `init` | Scaffold a new package. | Template choice and generated starter scripts. |
-| `dev` | Start local development. | Worker-only defaults, Vite auto-detection, logging, and persistence. |
+| `dev` | Start local development. | Worker-only defaults, Vite auto-detection, `ref()` service workers, runtime-port selection, logging, and persistence. |
 | `build` | Compile deploy-ready artifacts. | Environment resolution and Wrangler-facing output. |
 | `deploy` | Ship explicitly to production or preview. | Target selection, dry runs, preview naming, messages, and tags. |
 | `types` | Generate `env.d.ts` and typed bindings. | Custom output paths plus entrypoint and Durable Object discovery. |
-| `doctor` | Check local project health. | Config, package, TypeScript, Vite, and generated artifact diagnostics. |
-| `config` | Print resolved config. | `print`, raw Devflare JSON, or compiled Wrangler JSON. |
+| `doctor` | Check local project health. | Config, package, TypeScript, Vite, scope-aware local/deploy artifact diagnostics, and optional plugin guidance. |
+| `config` | Print resolved config. | `print`, raw Devflare JSON, compiled Wrangler JSON, and build/local/deploy resolution phases. |
 | `account` | Inspect Cloudflare account inventories and limits. | Resource lists, usage limits, and interactive global/workspace selection. |
 | `login` | Authenticate with Cloudflare via Wrangler. | `--force` behavior and reuse of existing sessions. |
 | `previews` | Operate on preview lifecycle state. | `list`, `bindings`, and `cleanup`. |
@@ -1352,7 +1352,11 @@ When the job changes from building to operating, switch command families instead
 ##### Key points
 
 - Run `types` after binding or entrypoint changes so `env.d.ts` stays honest.
+- Use `dev --runtime-port <port>` or `DEVFLARE_RUNTIME_PORT` when another local project already owns the default 8787 runtime port.
+- Use `config --phase local --format wrangler` when you want local config inspection without Cloudflare account lookups.
+- Use `ref()` service bindings for local full-stack packages; Devflare starts those referenced workers in CLI dev and exposes them as Vite auxiliary workers for framework dev.
 - Run `build` or `config print --format wrangler` when the compiled shape matters more than the dev server feeling healthy.
+- Use `doctor --scope local` when generated deploy artifacts are intentionally absent during a local-only loop.
 - Keep preview and production intent explicit in the final deploy command instead of hiding it in a generic script name.
 - Use the nested help pages when a lifecycle command reaches `--apply`, account selection, rollback, or cleanup territory.
 
@@ -1389,7 +1393,8 @@ bunx --bun devflare deploy --prod
 
 ```bash
 bunx --bun devflare config print --format wrangler
-bunx --bun devflare doctor
+bunx --bun devflare config --phase local --format wrangler
+bunx --bun devflare doctor --scope local
 bunx --bun devflare previews bindings --scope next
 bunx --bun devflare productions versions
 ```

package/README.md

@@ -17,10 +17,11 @@ For a worker-only project, install only Devflare:
 bun add -d devflare
 ```
 
-For Vite-backed apps, add Vite and the Cloudflare Vite plugin:
+For Vite-backed apps, add Vite. Add the Cloudflare Vite plugin only when your
+own `vite.config.*` calls it directly:
 
 ```bash
-bun add -d devflare vite @cloudflare/vite-plugin
+bun add -d devflare vite
 ```
 
 Assumptions used by the examples: Wrangler 4, Miniflare 4,
@@ -182,6 +183,13 @@ for examples with file paths.
 | `devflare version` | print the installed version |
 | `devflare worker` | run Worker control-plane helpers |
 
+Useful local-first switches:
+
+- `devflare dev --runtime-port 8788` or `DEVFLARE_RUNTIME_PORT=8788` moves the local Miniflare runtime/bridge off the default `127.0.0.1:8787`. `--bridge-port` and `DEVFLARE_BRIDGE_PORT` are aliases for the same runtime port.
+- `devflare doctor --scope local` skips deploy-readiness artifact warnings during a local-only loop.
+- `devflare config --phase local --format wrangler` prints the local-runtime Wrangler shape without Cloudflare account resource lookups.
+- `devflare dev` and `devflare/vite` start `ref()` service-binding workers inside the same local runtime, including their local KV, D1, R2, Queue producer/consumer, vars, Durable Objects, and other Miniflare-backed bindings.
+
 ## Support Stance Index
 
 The full support matrix is in `/docs/feature-index`. The short version is:

package/dist/browser.js

@@ -3,7 +3,7 @@ import {
 } from "./index-62b3gt2g.js";
 import {
   env
-} from "./index-0wa0ebm1.js";
+} from "./index-nxkesg55.js";
 import {
   durableObject,
   getDurableObjectOptions
@@ -14,8 +14,8 @@ import {
   getClient,
   initEnv,
   setBindingHints
-} from "./index-vrps1gky.js";
-import"./index-kgstnk6g.js";
+} from "./index-tknbyxzn.js";
+import"./index-hpwa6vsw.js";
 import {
   defineConfig,
   ref

package/dist/build-b1z6wqet.js

@@ -0,0 +1,54 @@
+import {
+  prepareBuildArtifacts
+} from "./index-kxc4gtyt.js";
+import"./index-aabgympv.js";
+import"./index-z9gy8w6b.js";
+import"./index-gn5wy09x.js";
+import"./index-627srx16.js";
+import {
+  createCliTheme,
+  cyanBold,
+  dim,
+  logLine
+} from "./index-stgn34cr.js";
+import"./index-3t6rypgc.js";
+import"./index-gq39t0rx.js";
+import"./index-t4fhcx1n.js";
+import"./index-8x745h59.js";
+import"./index-qf2dkqxh.js";
+import"./index-qwgr4q7s.js";
+import"./index-65e7xx1a.js";
+import"./index-vhqww6tt.js";
+import"./index-c3nxftnp.js";
+import"./index-syscwrjp.js";
+import"./index-1d4jg11n.js";
+import"./index-mg8vwqxf.js";
+import"./index-z40mjts9.js";
+import"./index-q8f4kawk.js";
+import"./index-37x76zdn.js";
+
+// src/cli/commands/build.ts
+async function runBuildCommand(parsed, logger, options) {
+  const theme = createCliTheme(parsed.options);
+  logLine(logger);
+  logLine(logger, `${cyanBold("build", theme)} ${dim("Preparing production artifacts", theme)}`);
+  try {
+    await prepareBuildArtifacts(parsed, logger, options);
+    logger.success("Generated .devflare/wrangler.jsonc");
+    logger.success("Generated .devflare/build/wrangler.jsonc");
+    logger.success("Generated .wrangler/deploy/config.json");
+    logger.success("Build complete!");
+    return { exitCode: 0 };
+  } catch (error) {
+    if (error instanceof Error) {
+      logger.error("Build failed:", error.message);
+      if (parsed.options.debug) {
+        logger.error(error.stack);
+      }
+    }
+    return { exitCode: 1 };
+  }
+}
+export {
+  runBuildCommand
+};

package/dist/build-x7maz3eb.js

@@ -0,0 +1,54 @@
+import {
+  prepareBuildArtifacts
+} from "./index-dgww0ewn.js";
+import"./index-aabgympv.js";
+import"./index-z9gy8w6b.js";
+import"./index-gn5wy09x.js";
+import"./index-627srx16.js";
+import {
+  createCliTheme,
+  cyanBold,
+  dim,
+  logLine
+} from "./index-stgn34cr.js";
+import"./index-3t6rypgc.js";
+import"./index-666tdx14.js";
+import"./index-05pbj4hy.js";
+import"./index-p7q23nce.js";
+import"./index-3edvz3hs.js";
+import"./index-qwgr4q7s.js";
+import"./index-aqrwyy57.js";
+import"./index-vhqww6tt.js";
+import"./index-c3nxftnp.js";
+import"./index-syscwrjp.js";
+import"./index-1d4jg11n.js";
+import"./index-mg8vwqxf.js";
+import"./index-z40mjts9.js";
+import"./index-q8f4kawk.js";
+import"./index-37x76zdn.js";
+
+// src/cli/commands/build.ts
+async function runBuildCommand(parsed, logger, options) {
+  const theme = createCliTheme(parsed.options);
+  logLine(logger);
+  logLine(logger, `${cyanBold("build", theme)} ${dim("Preparing production artifacts", theme)}`);
+  try {
+    await prepareBuildArtifacts(parsed, logger, options);
+    logger.success("Generated .devflare/wrangler.jsonc");
+    logger.success("Generated .devflare/build/wrangler.jsonc");
+    logger.success("Generated .wrangler/deploy/config.json");
+    logger.success("Build complete!");
+    return { exitCode: 0 };
+  } catch (error) {
+    if (error instanceof Error) {
+      logger.error("Build failed:", error.message);
+      if (parsed.options.debug) {
+        logger.error(error.stack);
+      }
+    }
+    return { exitCode: 1 };
+  }
+}
+export {
+  runBuildCommand
+};

package/dist/cli/commands/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAG9C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAMjE,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,SAAS,CAAC,CA6CpB"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAS9C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAoCjE,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,SAAS,CAAC,CA4DpB"}

package/dist/cli/commands/dev.d.ts

@@ -1,4 +1,5 @@
 import { type ConsolaInstance } from 'consola';
 import type { ParsedArgs, CliOptions, CliResult } from '../index';
+export declare function resolveDevRuntimePort(options: Record<string, string | boolean>, env?: NodeJS.ProcessEnv): number;
 export declare function runDevCommand(parsed: ParsedArgs, logger: ConsolaInstance, options: CliOptions): Promise<CliResult>;
 //# sourceMappingURL=dev.d.ts.map

package/dist/cli/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dev.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE7D,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAqEjE,wBAAsB,aAAa,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,SAAS,CAAC,CAkKpB"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dev.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE7D,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AA4CjE,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EACzC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,MAAM,CAYR;AAsDD,wBAAsB,aAAa,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,SAAS,CAAC,CA2KpB"}

package/dist/cli/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAcjE,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,SAAS,CAAC,CA8OpB"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAejE,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,UAAU,GACjB,OAAO,CAAC,SAAS,CAAC,CA0PpB"}

package/dist/cli/help-pages/pages/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/cli/help-pages/pages/core.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGxC,eAAO,MAAM,eAAe,EAAE,QAAQ,EA4VrC,CAAA;AAED,eAAO,MAAM,aAAa,2LAAW,CAAA"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/cli/help-pages/pages/core.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGxC,eAAO,MAAM,eAAe,EAAE,QAAQ,EA4WrC,CAAA;AAED,eAAO,MAAM,aAAa,2LAAW,CAAA"}

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 import {
   parseArgs,
   runCli
-} from "../index-h5dqna7q.js";
+} from "../index-pt49cgjv.js";
 import"../index-627srx16.js";
 import"../index-stgn34cr.js";
 import"../index-3t6rypgc.js";

package/dist/config-qj5jw8km.js

@@ -0,0 +1,93 @@
+import {
+  compileBuildConfig,
+  compileConfig
+} from "./index-c3nxftnp.js";
+import {
+  ConfigResourceResolutionError,
+  loadConfig,
+  loadResolvedConfig,
+  resolveResources
+} from "./index-syscwrjp.js";
+import"./index-1d4jg11n.js";
+import"./index-mg8vwqxf.js";
+import"./index-z40mjts9.js";
+import"./index-q8f4kawk.js";
+import"./index-37x76zdn.js";
+
+// src/cli/commands/config.ts
+function isSupportedFormat(value) {
+  return value === "devflare" || value === "wrangler";
+}
+function isSupportedPhase(value) {
+  return value === "build" || value === "local" || value === "deploy";
+}
+async function loadConfigForPhase(options) {
+  if (options.phase === "deploy") {
+    return await loadResolvedConfig({
+      cwd: options.cwd,
+      configFile: options.configPath,
+      environment: options.environment
+    });
+  }
+  const config = await loadConfig({
+    cwd: options.cwd,
+    configFile: options.configPath
+  });
+  return await resolveResources(config, {
+    phase: options.phase,
+    environment: options.environment
+  });
+}
+async function runConfigCommand(parsed, logger, options) {
+  const cwd = options.cwd || process.cwd();
+  const configPath = parsed.options.config;
+  const environment = parsed.options.env;
+  const subcommand = parsed.args[0] ?? "print";
+  const formatOption = parsed.options.format;
+  const format = formatOption ?? "devflare";
+  const phaseOption = parsed.options.local === true ? "local" : parsed.options.phase ?? "deploy";
+  if (subcommand !== "print") {
+    logger.error(`Unknown config subcommand: ${subcommand}`);
+    logger.info("Supported subcommands: print");
+    return { exitCode: 1 };
+  }
+  if (!isSupportedFormat(format)) {
+    logger.error(`Unsupported config format: ${format}`);
+    logger.info("Supported formats: devflare, wrangler");
+    return { exitCode: 1 };
+  }
+  if (!isSupportedPhase(phaseOption)) {
+    logger.error(`Unsupported config phase: ${phaseOption}`);
+    logger.info("Supported phases: build, local, deploy");
+    return { exitCode: 1 };
+  }
+  try {
+    const resolvedConfig = await loadConfigForPhase({
+      cwd,
+      configPath,
+      environment,
+      phase: phaseOption
+    });
+    const output = format === "wrangler" ? phaseOption === "build" ? compileBuildConfig(resolvedConfig, undefined, { alreadyResolved: true }) : compileConfig(resolvedConfig) : resolvedConfig;
+    const text = JSON.stringify(output, null, "\t");
+    if (!options.silent) {
+      process.stdout.write(`${text}
+`);
+    }
+    return {
+      exitCode: 0,
+      output: text
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      logger.error("Config command failed:", error.message);
+      if (error instanceof ConfigResourceResolutionError) {
+        logger.info("For offline inspection, run `devflare config --phase local` or `devflare config --phase build --format wrangler`.");
+      }
+    }
+    return { exitCode: 1 };
+  }
+}
+export {
+  runConfigCommand
+};