@lukoweb/apitogo 0.2.18 → 0.2.21

package/docs/cli/setup.md

@@ -26,13 +26,25 @@ commands add it to your project and `npm install` puts it on `node_modules/.bin`
 
 ### New project (recommended)
 
-`npx @lukoweb/apitogo@latest init` scaffolds into `./dev-portal` by default (pass a folder name to
-override). It installs dependencies, writes `apitogo.config.json` and secrets artifacts, and
-auto-wires nearby OpenAPI (`openapi.yaml` / `swagger.yaml`) plus markdown in `docs/` / `doc/` /
-`documents/` / `documentation/` folders:
+`npx @lukoweb/apitogo@latest init` creates a config version 2 project in the current folder. It
+shows what it will create and asks first (pass `--yes` to skip the question), writes
+`apitogo.config.json`, uses an existing `docs/` folder in place, and, in a new folder, creates
+`package.json` and installs `@lukoweb/apitogo`, `react` and `react-dom`:
 
 ```bash
-npx @lukoweb/apitogo@latest init
+mkdir my-portal && cd my-portal
+npx @lukoweb/apitogo@latest init --name "Books API"
+npx apitogo run
+```
+
+In an existing project the tool never edits your `package.json`. It prints the install command to
+run instead.
+
+The older scaffold (a `dev-portal` folder with secrets artifacts and automatic OpenAPI wiring) is
+still available with `--no-v2`:
+
+```bash
+npx @lukoweb/apitogo@latest init --no-v2
 cd dev-portal
 npx apitogo run
 ```
@@ -47,14 +59,16 @@ npx apitogo run
 
 #### Scaffold options
 
-| Flag                      | Effect                                                       |
-| ------------------------- | ------------------------------------------------------------ |
-| `[dir]`                   | Target folder (default `dev-portal`)                         |
-| `--name <string>`         | Site / package name (also used when `dir` is `.`)            |
-| `--no-install`            | Skip `npm install` after scaffold                            |
-| `--overwrite`             | Replace an existing non-empty target directory               |
-| `--json`                  | Print a JSON result payload on stdout                        |
-| `--openapi-search <mode>` | Auto-discover OpenAPI: `nearby` (default), `site`, or `none` |
+| Flag                      | Effect                                                                   |
+| ------------------------- | ------------------------------------------------------------------------ |
+| `[dir]`                   | Target folder (default: the current folder; `dev-portal` with `--no-v2`) |
+| `--name <string>`         | Site / package name (also used when `dir` is `.`)                        |
+| `--no-install`            | Skip `npm install` after scaffold                                        |
+| `--no-v2`                 | Use the older `dev-portal` scaffold instead of config version 2          |
+| `--yes`                   | Do not ask for confirmation (config version 2)                           |
+| `--overwrite`             | Replace an existing non-empty target directory                           |
+| `--json`                  | Print a JSON result payload on stdout                                    |
+| `--openapi-search <mode>` | Auto-discover OpenAPI: `nearby` (default), `site`, or `none`             |
 
 `npx @lukoweb/apitogo init` is local only — it does not call the platform. After `config`, run
 `npx apitogo run` to preview, then `npx apitogo deploy` when ready to go live.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.18",
+  "version": "0.2.21",
   "type": "module",
   "sideEffects": [
     "**/*.css",

package/src/config/v2/wrapper.ts

@@ -10,6 +10,7 @@ import { docRoutes, type HomeRedirect, homeRedirect } from "./home-redirect.js";
 import {
   hasCapability,
   missingManifestServices,
+  requiredServices,
   type ServiceManifest,
   serviceReady,
   stubManifest,
@@ -405,7 +406,8 @@ export async function preparePortal(
     if (mode === "production") {
       issues.push(...missingManifestServices(resolved, manifest));
     }
-  } else if (mode === "development") {
+  } else if (mode === "development" && requiredServices(resolved).length > 0) {
+    // Only a portal that depends on a service gets the stand-in: a docs-only portal has nothing to stand in for.
     effective = stubManifest(resolved);
     manifestSource = "preview-stub";
   } else {

package/src/vite/config.ts

@@ -19,6 +19,7 @@ import { loadDevPortalViteDefines } from "./dev-portal-env.js";
 import { findPackageRoot } from "./package-root.js";
 import { ensurePagefindDevStub } from "./pagefind-dev-stub.js";
 import vitePlugin from "./plugin.js";
+import { devServerAllow, stateIgnore } from "./watch-ignore.js";
 import { getZuploSystemConfigurations } from "./zuplo.js";
 
 /** Resolved absolute public directory (Vite default: `<root>/public`). */
@@ -85,6 +86,9 @@ export async function getViteConfig(
     ]),
   );
 
+  // The workspace of a config version 2 portal links back to its own project; the watcher must not follow that.
+  const ignoreState = stateIgnore(dir);
+
   if (ZuploEnv.isZuplo) {
     dotenv.config({
       path: path.resolve(config.__meta.rootDir, "../.env.zuplo"),
@@ -140,7 +144,7 @@ export async function getViteConfig(
       middlewareMode: true,
       open: true,
       fs: {
-        allow: [dir, path.dirname(dir)],
+        allow: devServerAllow(dir, config.__meta.moduleDir),
       },
       watch: {
         ignored: [
@@ -149,6 +153,7 @@ export async function getViteConfig(
           `${dir}/.git`,
           `${config.__meta.moduleDir}/src/vite`,
           `${config.__meta.moduleDir}/src/cli`,
+          ...(ignoreState ? [ignoreState] : []),
         ],
       },
     },

package/src/vite/watch-ignore.ts

@@ -0,0 +1,70 @@
+import { lstatSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * A config version 2 portal builds from `<state>/generated/`, where `content` is a link to the project folder.
+ * That folder holds the state folder itself (`.apitogo/` or `apitogo/.state/`), which holds `generated/content`
+ * again, so a file watcher that follows the link goes round forever (ENAMETOOLONG).
+ */
+const STATE_INSIDE_CONTENT =
+  /[\\/]content[\\/](?:\.apitogo|apitogo[\\/]\.state)(?:[\\/]|$)/;
+
+const within = (base: string, file: string) =>
+  file === base || file.startsWith(base + path.sep);
+
+const unique = (paths: string[]) => [...new Set(paths)];
+
+/** Whether `root` is the site root (`<state>/generated`) of a config version 2 workspace: it has the `content` link. */
+function isWorkspace(root: string): boolean {
+  try {
+    return (
+      path.basename(root) === "generated" &&
+      lstatSync(path.join(root, "content")).isSymbolicLink()
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The tenant's own folder of a config version 2 workspace (what `content` links to), or `undefined` for any other
+ * project. The site root sits inside the state folder, so the folder that holds `node_modules` and the pages is
+ * outside it and the dev server has to be told it may serve files from there.
+ */
+export function tenantDir(root: string): string | undefined {
+  return isWorkspace(root)
+    ? realpathSync(path.join(root, "content"))
+    : undefined;
+}
+
+/**
+ * What the dev server's watcher must leave alone in a config version 2 workspace, or `undefined` for any other
+ * project. The watcher meets the state folder twice: below the `content` link and, after resolving the link,
+ * by its real path. So the whole state folder is skipped, except `generated/` itself (the site root) and the
+ * tenant's own files.
+ */
+export function stateIgnore(
+  root: string,
+): ((file: string) => boolean) | undefined {
+  if (!isWorkspace(root)) return undefined;
+
+  const state = path.dirname(root);
+  const states = unique([state, realpathSync(state)]);
+  const roots = unique([root, realpathSync(root)]);
+
+  return (file) => {
+    if (!states.some((base) => within(base, file))) return false;
+    if (!roots.some((base) => within(base, file))) return true;
+    return STATE_INSIDE_CONTENT.test(file);
+  };
+}
+
+/**
+ * The folders the dev server may serve files from. The site root of a config version 2 workspace sits inside the
+ * state folder, so the package (`node_modules`) and the tenant's pages are outside it. Without them the page's main
+ * script fails with "Failed to load url ... Does the file exist?" and the server stops.
+ */
+export function devServerAllow(root: string, moduleDir: string): string[] {
+  const tenant = tenantDir(root);
+  return [root, path.dirname(root), moduleDir, ...(tenant ? [tenant] : [])];
+}