@hatchkit/dev-plugin-next 0.1.45

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export interface LocalDevOptions {
+    /** Override slug resolution. Useful when the package.json name doesn't
+     *  match the desired subdomain (e.g. scoped packages, monorepo
+     *  workspaces). When unset, the plugin walks up from cwd looking for
+     *  `.hatchkit.json` (preferred) then package.json. */
+    slug?: string;
+    /** Default port to assume when the dev server hasn't told us yet.
+     *  Next.js defaults to 3000; hatchkit's scaffold pins a random 3xxx
+     *  per project, so callers usually override this. */
+    defaultPort?: number;
+    /** Disable banner output. Side effects (Caddy fragment write,
+     *  tailscale probe) still run. */
+    silent?: boolean;
+}
+/** Wrap a Next.js config with hatchkit's local-dev integration. */
+export declare function withLocalDev<TConfig>(nextConfig: TConfig, options?: LocalDevOptions): TConfig;
+//# 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":"AAuDA,MAAM,WAAW,eAAe;IAC9B;;;0DAGsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;yDAEqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;sCACkC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAUjG"}

package/dist/index.js

@@ -0,0 +1,185 @@
+/*
+ * @hatchkit/dev-plugin-next — Next.js integration for hatchkit's
+ * Tailscale-served dev URL flow.
+ *
+ * Usage:
+ *
+ *   // next.config.ts
+ *   import { withLocalDev } from "@hatchkit/dev-plugin-next";
+ *
+ *   export default withLocalDev({
+ *     reactStrictMode: true,
+ *     // ...your normal Next config
+ *   }, {
+ *     slug: "raptor-runner", // optional override
+ *   });
+ *
+ * What it does on `next dev` startup (only — `next build` / `next start`
+ * are pass-through no-ops):
+ *
+ *   1. Resolves the project's slug from (in order): the explicit
+ *      `slug` option → `.hatchkit.json` (walking up from cwd) →
+ *      package.json `name`.
+ *   2. Sniffs the dev port from `process.env.PORT` or `--port` argv
+ *      (Next's own resolution path).
+ *   3. Writes ~/.config/dev/projects/<slug>.caddy with a
+ *      `reverse_proxy 127.0.0.1:<port>` directive. Caddy's --watch
+ *      picks the change up without a restart.
+ *   4. Probes `tailscale serve status` for the TCP=443 bridge that
+ *      `hatchkit dev-setup init` registers once per machine.
+ *   5. Prints a one-line `Tailscale: https://<slug>.local.ricoslabs.com/`
+ *      banner alongside Next's own startup output.
+ *
+ * Failure modes (no caddy fragment, no TCP bridge, tailscale offline)
+ * surface as inline hints. The plugin never throws — a broken local-dev
+ * pipeline should not break the dev server.
+ *
+ * Opt out entirely with `HATCHKIT_LOCAL_DEV=0`.
+ *
+ * The plugin does NOT touch Next's `basePath` / `assetPrefix` /
+ * routing. Caddy proxies verbatim and Next serves at `/` — HMR/WS
+ * paths stay unchanged, no app-side config needed.
+ */
+import { isLocalDevActive, localDevUrl, readCaddyPort, resolveSlug, tailscaleIdentity, tailscaleServeTcpTarget, writeProjectFragment, } from "@hatchkit/dev-shared";
+/** Wrap a Next.js config with hatchkit's local-dev integration. */
+export function withLocalDev(nextConfig, options = {}) {
+    // Only fire side effects in `next dev`. Production builds + `next start`
+    // get the bare config back; same behaviour as if the plugin weren't there.
+    if (isDevCommand() && process.env.HATCHKIT_LOCAL_DEV !== "0") {
+        // Schedule async so we don't block Next's config loader. The Promise
+        // resolves into stdout — Next's logger has already cleared by the
+        // time we print, so our banner shows up below Next's "Ready" line.
+        void initLocalDev(options);
+    }
+    return nextConfig;
+}
+function isDevCommand() {
+    // Next sets NODE_ENV="development" during `next dev`. The argv check
+    // is the belt-and-braces fallback for harnesses (turbo, custom
+    // servers) that load the config without setting NODE_ENV first.
+    if (process.env.NODE_ENV === "development")
+        return true;
+    const argv = process.argv.slice(2);
+    return argv.includes("dev") || argv.includes("--dev");
+}
+async function initLocalDev(options) {
+    // Wait one tick so Next's own banner ("▲ Next.js …", "Ready in …ms")
+    // has flushed before we tack our line on. Picking a fixed delay is
+    // unavoidable here — Next 14/15 don't expose a "server-listening"
+    // hook to a config consumer. 1.5s is the empirically reliable point
+    // across Next 14, 15, and Turbopack on Rico's machine; if the user's
+    // dev server takes longer to come up our banner still prints, just
+    // mixed in with later HMR logs (harmless).
+    await sleep(1500);
+    const resolved = resolveSlug({ explicit: options.slug });
+    if (!resolved) {
+        log("[hatchkit] local-dev disabled: no slug found (set { slug } in withLocalDev or add a name to package.json).");
+        return;
+    }
+    const port = detectDevPort(options.defaultPort);
+    if (port === null) {
+        log("[hatchkit] local-dev disabled: couldn't detect dev port from PORT env or argv.");
+        return;
+    }
+    // Write/update the fragment first so Caddy reload picks up the right port
+    // before we probe for the bridge — saves the user one re-run when the
+    // port changed.
+    let fragmentResult = "unchanged";
+    try {
+        fragmentResult = writeProjectFragment(resolved.slug, port);
+    }
+    catch (err) {
+        log(`[hatchkit] local-dev: failed to write Caddy fragment (${err.message}). Banner suppressed.`);
+        return;
+    }
+    // Probe the host-wide bridge. Three outcomes drive the banner shape:
+    //   1. host-feature not active (no Caddyfile marker) → silent encouragement
+    //   2. active but no TCP=443 → red hint with one-liner fix
+    //   3. active + TCP=443 → green banner with the public URL
+    if (!isLocalDevActive()) {
+        log(`[hatchkit] local-dev: ${resolved.slug}.caddy ${fragmentResult}, but host bridge not configured.`);
+        log("            Run `hatchkit dev-setup init` once to enable Tailscale URLs.");
+        return;
+    }
+    const caddyPort = readCaddyPort();
+    if (caddyPort === null) {
+        log("[hatchkit] local-dev: Caddyfile is hatchkit-managed but has no https_port. Re-run `hatchkit dev-setup init`.");
+        return;
+    }
+    const tsId = await tailscaleIdentity();
+    if (!tsId) {
+        // Tailscale offline / not installed — local-dev only matters when
+        // the user wants peers to reach this machine. Treat as silent no-op.
+        return;
+    }
+    const tcpTarget = await tailscaleServeTcpTarget();
+    if (tcpTarget === null) {
+        log(`[hatchkit] local-dev: no port-443 bridge configured.`);
+        log(`            Run once: tailscale serve --bg --tcp=443 tcp://localhost:${caddyPort}`);
+        return;
+    }
+    if (tcpTarget !== caddyPort) {
+        log(`[hatchkit] local-dev: tailscale serve points at localhost:${tcpTarget} but Caddy listens on ${caddyPort}.`);
+        log("            Run: `hatchkit dev-setup init` to reconcile.");
+        return;
+    }
+    if (!options.silent) {
+        log(`[hatchkit] Tailscale: ${localDevUrl(resolved.slug)}  (slug from ${describeSource(resolved)})`);
+    }
+}
+function detectDevPort(fallback) {
+    // Order matches Next's own resolution: explicit env var, then -p / --port
+    // argv, then the framework's default.
+    const fromEnv = numericEnv(process.env.PORT);
+    if (fromEnv !== null)
+        return fromEnv;
+    const fromArgv = numericPortArgv(process.argv);
+    if (fromArgv !== null)
+        return fromArgv;
+    if (fallback !== undefined)
+        return fallback;
+    return 3000;
+}
+function numericEnv(v) {
+    if (!v)
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+function numericPortArgv(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-p" || a === "--port") {
+            const next = argv[i + 1];
+            const n = next ? Number(next) : Number.NaN;
+            if (Number.isFinite(n) && n > 0)
+                return n;
+        }
+        else if (a?.startsWith("--port=")) {
+            const n = Number(a.slice("--port=".length));
+            if (Number.isFinite(n) && n > 0)
+                return n;
+        }
+    }
+    return null;
+}
+function describeSource(resolved) {
+    switch (resolved.source) {
+        case "explicit":
+            return "withLocalDev option";
+        case "manifest":
+            return ".hatchkit.json";
+        case "package-json":
+            return "package.json";
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function log(line) {
+    // stderr so HMR/output paths stay on stdout and tools that pipe Next's
+    // output (e.g. concurrently, mprocs) don't merge our banner into their
+    // stdout buffer in surprising ways.
+    process.stderr.write(`${line}\n`);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@hatchkit/dev-plugin-next",
+  "version": "0.1.45",
+  "description": "Next.js plugin for hatchkit's local-dev integration. Writes the project's Caddy fragment on `next dev` startup and prints a Tailscale-URL banner alongside Next's own startup output.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@hatchkit/dev-shared": "0.1.45"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "next": "^15.1.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}