@lukoweb/apitogo 0.1.95 → 0.1.97

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/dist/cli/cli.js +643 -406
  2. package/dist/declarations/cli/platform/helpers/openapi.d.ts +1 -2
  3. package/dist/declarations/cli/scaffold/discover-openapi-files.d.ts +15 -0
  4. package/docs/cli/commands.md +43 -42
  5. package/docs/cli/go-live.md +1 -1
  6. package/docs/cli/setup.md +46 -29
  7. package/docs/cli/shape.md +2 -2
  8. package/docs/deploy/apitogo.md +1 -1
  9. package/package.json +1 -1
  10. package/src/vite/config.ts +3 -0
  11. package/src/vite/plugin-offroot-resolve.ts +71 -0
  12. package/src/vite/plugin.ts +2 -0
package/dist/declarations/cli/platform/helpers/openapi.d.ts CHANGED
@@ -1,10 +1,10 @@
1
+ export { OPENAPI_BASENAMES, OPENAPI_NOT_FOUND_SUGGESTION, } from "../../scaffold/discover-openapi-files.js";
1
2
  export interface ValidateOpenApiResult {
2
3
  valid: boolean;
3
4
  errors: string[];
4
5
  version?: string;
5
6
  title?: string;
6
7
  }
7
- export declare const OPENAPI_BASENAMES: readonly ["openapi.yaml", "openapi.yml", "openapi.json", "swagger.yaml", "swagger.yml", "swagger.json"];
8
8
  export interface NearbyOpenApiDiscovery {
9
9
  status: "found" | "not_found" | "invalid";
10
10
  selectedPath?: string;
@@ -18,7 +18,6 @@ export interface NearbyOpenApiDiscovery {
18
18
  }>;
19
19
  }
20
20
  export declare function discoverNearbyOpenApi(siteDirectory: string): Promise<NearbyOpenApiDiscovery>;
21
- export declare const OPENAPI_NOT_FOUND_SUGGESTION = "No OpenAPI file found near the site (checked parent, sibling folders, and the site directory for openapi.yaml|yml|json / swagger.yaml|yml|json). Ask the user for a path, or offer to draft a starter OpenAPI 3 spec from their API description, write it next to the site (e.g. ../openapi.yaml), then call set_dev_portal_openapi.";
22
21
  export declare const OPENAPI_NOT_FOUND_AGENT_INSTRUCTION = "No OpenAPI was auto-discovered. Ask if they already have a spec path; if not, offer to create a starter OpenAPI 3 file for them from a short description of their API (paths/operations), write it beside the site, then call set_dev_portal_openapi. Do not invent a large fake API unless they ask for placeholders.";
23
22
  export declare const OPENAPI_WIRED_AGENT_INSTRUCTION = "OpenAPI was auto-discovered and wired to /api. Do not ask to add OpenAPI unless the user wants a different spec. Restart local preview after create so /api registers.";
24
23
  export declare function validateOpenApiFile(filePath: string): Promise<ValidateOpenApiResult>;
package/dist/declarations/cli/scaffold/discover-openapi-files.d.ts ADDED
@@ -0,0 +1,15 @@
1
+ export declare const OPENAPI_BASENAMES: readonly ["openapi.yaml", "openapi.yml", "openapi.json", "swagger.yaml", "swagger.yml", "swagger.json"];
2
+ export declare const OPENAPI_NOT_FOUND_SUGGESTION = "No OpenAPI file found near the site (checked parent, sibling folders, and the site directory for openapi.yaml|yml|json / swagger.yaml|yml|json). Ask the user for a path, or offer to draft a starter OpenAPI 3 spec from their API description, write it next to the site (e.g. ../openapi.yaml), then call set_dev_portal_openapi.";
3
+ export type OpenApiFileSearch = {
4
+ candidates: string[];
5
+ searchedDirectories: string[];
6
+ };
7
+ export declare function collectSiteOpenApiFiles(siteDirectory: string): Promise<OpenApiFileSearch>;
8
+ export declare function collectNearbyOpenApiFiles(siteDirectory: string): Promise<OpenApiFileSearch>;
9
+ export type LiteOpenApiParse = {
10
+ valid: boolean;
11
+ version?: string;
12
+ title?: string;
13
+ errors: string[];
14
+ };
15
+ export declare function liteParseOpenApi(content: string, filePath: string): LiteOpenApiParse;
package/docs/cli/commands.md CHANGED
@@ -10,59 +10,60 @@ same commands so agents and humans get identical behavior.
10
10
 
11
11
  ## Lifecycle (prefer these)
12
12
 
13
- | Command | Role |
14
- | ------- | ---- |
15
- | `init` | Scaffold portal (create-apitogo + OpenAPI discovery + secrets) |
16
- | `config` / `make-config` | Write or update `apitogo.config.json` (interactive or flags) |
17
- | `dev` | Local preview server |
18
- | `build` | Production build (`--preview` to serve locally) |
19
- | `check` | Publish readiness (secrets, manifest, site validation) |
20
- | `project create` | Create a platform project (plan unselected) |
21
- | `apply` | Publish config to platform (apihub + portal) |
22
- | `status` | Account, project, and live readiness |
23
- | `teardown --yes` | Delete the linked platform project |
13
+ | Command | Role |
14
+ | ------------------------ | -------------------------------------------------------------- |
15
+ | `init` | Scaffold portal (create-apitogo + OpenAPI discovery + secrets) |
16
+ | `config` / `make-config` | Write or update `apitogo.config.json` (interactive or flags) |
17
+ | `dev` | Local preview server |
18
+ | `build` | Production build (`--preview` to serve locally) |
19
+ | `check` | Publish readiness (secrets, manifest, site validation) |
20
+ | `project create` | Create a platform project (plan unselected) |
21
+ | `apply` | Publish config to platform (apihub + portal) |
22
+ | `status` | Account, project, and live readiness |
23
+ | `teardown --yes` | Delete the linked platform project |
24
24
 
25
25
  ## Scaffold and config
26
26
 
27
- | Command | Role |
28
- | ------- | ---- |
29
- | `init [dir]` | Named folder; `--install` (default), `--overwrite`, `--json`, `--openapi-search` |
30
- | `config` | Interactive on TTY; flags: `--openapi`, `--page-*`, `--plan`, `--backend`, `--theme`, `--patch`, `--json` |
27
+ | Command | Role |
28
+ | ------------ | --------------------------------------------------------------------------------------------------------- |
29
+ | `init [dir]` | Named folder; `--install` (default), `--overwrite`, `--json`, `--openapi-search` |
30
+ | `config` | Interactive on TTY; flags: `--openapi`, `--page-*`, `--plan`, `--backend`, `--theme`, `--patch`, `--json` |
31
31
 
32
- `npx @lukoweb/create-apitogo@latest` remains an interactive alternative for new folders.
33
- Pass `--typescript --eslint` to skip those prompts. See [Install the CLI](./setup.md#scaffold-options).
32
+ `npx @lukoweb/create-apitogo@latest` remains an interactive alternative for new folders. It
33
+ auto-wires nearby OpenAPI and `docs/`/`doc/` markdown after scaffold. Pass `--typescript --eslint`
34
+ to skip those prompts. See [Install the CLI](./setup.md#scaffold-options).
34
35
 
35
36
  See [Make config (CLI)](../configuration/make-config.mdx) for all `config` flags.
36
37
 
37
38
  ## Local development
38
39
 
39
- | Command | Role |
40
- | ------- | ---- |
41
- | `dev` | Run Vite dev server (`--port`, `--open`, `--ssr`) |
42
- | `build` | Production static build |
43
- | `build --preview` | Build then serve locally |
40
+ | Command | Role |
41
+ | ----------------- | ------------------------------------------------- |
42
+ | `dev` | Run Vite dev server (`--port`, `--open`, `--ssr`) |
43
+ | `build` | Production static build |
44
+ | `build --preview` | Build then serve locally |
44
45
 
45
46
  ## Platform (requires API credentials)
46
47
 
47
- | Command | Role |
48
- | ------- | ---- |
49
- | `project create --name` | Create platform project only |
50
- | `check` | Dry-run publish readiness |
51
- | `apply` | Full publish — project, plans, apihub, portal backend/frontend |
52
- | `apply --only <resource>` | Limit to `apihub`, `portal-backend`, or `portal-frontend` |
53
- | `apply --force` | Redeploy selected resources even when healthy |
54
- | `apply --platform-plan` | Select Free / Starter / Professional hosting |
55
- | `apply --resume-from` | Resume interrupted publish |
56
- | `status` | Whoami + project + live verification |
57
- | `teardown --yes` | Delete platform project (confirmation required) |
48
+ | Command | Role |
49
+ | ------------------------- | -------------------------------------------------------------- |
50
+ | `project create --name` | Create platform project only |
51
+ | `check` | Dry-run publish readiness |
52
+ | `apply` | Full publish — project, plans, apihub, portal backend/frontend |
53
+ | `apply --only <resource>` | Limit to `apihub`, `portal-backend`, or `portal-frontend` |
54
+ | `apply --force` | Redeploy selected resources even when healthy |
55
+ | `apply --platform-plan` | Select Free / Starter / Professional hosting |
56
+ | `apply --resume-from` | Resume interrupted publish |
57
+ | `status` | Whoami + project + live verification |
58
+ | `teardown --yes` | Delete platform project (confirmation required) |
58
59
 
59
60
  Env: `APITOGO_API_KEY_ID`, `APITOGO_API_SECRET`. Optional: `APITOGO_API_URL`.
60
61
 
61
62
  ## Hand-edit exceptions
62
63
 
63
- | Change | Where |
64
- | ----------------- | -------------------------------------------------- |
65
- | Home page content | `landing/LandingPage.tsx` |
64
+ | Change | Where |
65
+ | ----------------- | -------------------------------------------------------- |
66
+ | Home page content | `landing/LandingPage.tsx` |
66
67
  | Site footer | `apitogo.config.json` → `modules.landing.content.footer` |
67
68
 
68
69
  There is no CLI command for arbitrary home page content.
@@ -71,12 +72,12 @@ There is no CLI command for arbitrary home page content.
71
72
 
72
73
  These print a redirect message — use the replacement:
73
74
 
74
- | Removed | Use instead |
75
- | ------- | ----------- |
76
- | `deploy` | `apitogo apply` (optionally `--only portal-frontend`) |
77
- | `preview` | `apitogo build --preview` or `apitogo dev` |
78
- | `remove` | `apitogo teardown --yes` |
79
- | `configure-github-workflow` | `apitogo apply` |
75
+ | Removed | Use instead |
76
+ | --------------------------- | ----------------------------------------------------- |
77
+ | `deploy` | `apitogo apply` (optionally `--only portal-frontend`) |
78
+ | `preview` | `apitogo build --preview` or `apitogo dev` |
79
+ | `remove` | `apitogo teardown --yes` |
80
+ | `configure-github-workflow` | `apitogo apply` |
80
81
 
81
82
  ## Related
82
83
 
package/docs/cli/go-live.md CHANGED
@@ -39,7 +39,7 @@ gateway plans, and verifies the live site. `apitogo apply` is the source of trut
39
39
  ## Happy path
40
40
 
41
41
  ```bash
42
- cd ./my-portal
42
+ cd ./dev-portal
43
43
  apitogo apply --platform-plan free
44
44
  apitogo status
45
45
  ```
package/docs/cli/setup.md CHANGED
@@ -5,29 +5,46 @@ description:
5
5
  sidebar_icon: terminal
6
6
  ---
7
7
 
8
- Use the **`apitogo`** CLI (`@lukoweb/apitogo`) to scaffold a local portal, shape `apitogo.config.json`,
9
- preview with `apitogo dev`, and publish with `apitogo apply`. Platform commands (`apply`, `status`,
10
- `teardown`) use the same engine as MCP `publish_dev_portal`.
8
+ Use the **`apitogo`** CLI (`@lukoweb/apitogo`) to scaffold a local portal, shape
9
+ `apitogo.config.json`, preview with `apitogo dev`, and publish with `apitogo apply`. Platform
10
+ commands (`apply`, `status`, `teardown`) use the same engine as MCP `publish_dev_portal`.
11
11
 
12
12
  ## Prerequisites
13
13
 
14
14
  - **Node.js 20+**
15
- - Platform API credentials from [apitogo.com](https://apitogo.com) when you run `apitogo apply`
16
- (API key id + secret)
15
+ - Platform API credentials from [apitogo.com](https://apitogo.com) when you run `apitogo apply` (API
16
+ key id + secret)
17
17
 
18
18
  ## Install
19
19
 
20
- The CLI is the npm package **`@lukoweb/apitogo`**. It exposes the **`apitogo`** binary. You do not
21
- need a global install — scaffold commands add it to your project and `npm install` puts it on
22
- `node_modules/.bin`.
20
+ The CLI is the npm package **`@lukoweb/apitogo`**. It exposes the **`apitogo`** binary. Scaffold
21
+ commands add it to your project and `npm install` puts it on `node_modules/.bin`. A global install
22
+ is optional.
23
+
24
+ ### Global install
25
+
26
+ ```bash
27
+ npm install -g @lukoweb/apitogo
28
+ ```
29
+
30
+ Then run `apitogo` from any directory:
31
+
32
+ ```bash
33
+ apitogo --help
34
+ ```
35
+
36
+ Upgrade later with `npm install -g @lukoweb/apitogo@latest`. Uninstall with
37
+ `npm uninstall -g @lukoweb/apitogo`.
23
38
 
24
39
  ### New project (recommended)
25
40
 
26
- `npx @lukoweb/create-apitogo` scaffolds the site **and** installs `@lukoweb/apitogo` locally:
41
+ `npx @lukoweb/create-apitogo` scaffolds the site, installs `@lukoweb/apitogo` locally, and
42
+ auto-wires nearby OpenAPI (`openapi.yaml` / `swagger.yaml`) plus markdown in `docs/` / `doc/` /
43
+ `documents/` / `documentation/` folders:
27
44
 
28
45
  ```bash
29
46
  npx @lukoweb/create-apitogo@latest
30
- cd your-project-name
47
+ cd dev-portal
31
48
  npx apitogo config # interactive: backend, OpenAPI, pages, plans
32
49
  npm run dev
33
50
  ```
@@ -38,20 +55,20 @@ Also works with `pnpm create @lukoweb/apitogo`, `yarn create @lukoweb/apitogo`,
38
55
  Non-interactive:
39
56
 
40
57
  ```bash
41
- npx @lukoweb/create-apitogo@latest my-portal --typescript --eslint
42
- cd my-portal
58
+ npx @lukoweb/create-apitogo@latest dev-portal --typescript --eslint
59
+ cd dev-portal
43
60
  npx apitogo config
44
61
  ```
45
62
 
46
63
  #### Scaffold options
47
64
 
48
- | Flag | Effect |
49
- | ---- | ------ |
50
- | `--typescript` / `--ts` | TypeScript project |
51
- | `--javascript` / `--js` | JavaScript project |
52
- | `--eslint` | Add ESLint config |
53
- | `--no-eslint` | Skip ESLint |
54
- | `--include-examples` | Add starter docs and a sample OpenAPI spec (off unless passed) |
65
+ | Flag | Effect |
66
+ | ----------------------- | -------------------------------------------------------------- |
67
+ | `--typescript` / `--ts` | TypeScript project |
68
+ | `--javascript` / `--js` | JavaScript project |
69
+ | `--eslint` | Add ESLint config |
70
+ | `--no-eslint` | Skip ESLint |
71
+ | `--include-examples` | Add starter docs and a sample OpenAPI spec (off unless passed) |
55
72
 
56
73
  Omit flags to be prompted for TypeScript and ESLint. Example files are never prompted.
57
74
 
@@ -70,17 +87,17 @@ npx apitogo config
70
87
  npm run dev
71
88
  ```
72
89
 
73
- `apitogo init` is local only — it does not call the platform. After `config`, run `npm run dev`
74
- to preview, then `apitogo apply` when ready to go live.
90
+ `apitogo init` is local only — it does not call the platform. After `config`, run `npm run dev` to
91
+ preview, then `apitogo apply` when ready to go live.
75
92
 
76
93
  ### How to run `apitogo`
77
94
 
78
- | Situation | Command |
79
- | --------- | ------- |
95
+ | Situation | Command |
96
+ | ------------------------------------------------------------------- | --------------------------------------------------- |
80
97
  | After `npx @lukoweb/create-apitogo` or `npm install` in the project | `npx apitogo <command>` (e.g. `npx apitogo config`) |
81
- | Same, if `node_modules/.bin` is on your PATH | `apitogo <command>` |
82
- | One-off, no project yet | `npx @lukoweb/apitogo <command>` |
83
- | Optional global install | `npm install -g @lukoweb/apitogo` then `apitogo <command>` anywhere |
98
+ | Same, if `node_modules/.bin` is on your PATH | `apitogo <command>` |
99
+ | One-off, no project yet | `npx @lukoweb/apitogo <command>` |
100
+ | After [global install](#global-install) | `apitogo <command>` anywhere |
84
101
 
85
102
  `npm run dev` / `npm run build` use the project-local CLI via `package.json` scripts — no global
86
103
  install required.
@@ -96,9 +113,9 @@ Export these before `apitogo apply`, `apitogo status`, or `apitogo teardown`:
96
113
 
97
114
  Optional:
98
115
 
99
- | Variable | Purpose |
100
- | ------------------ | ---------------------------------------------------- |
101
- | `APITOGO_API_URL` | Override platform API base URL |
116
+ | Variable | Purpose |
117
+ | ------------------ | ---------------------------------------------------------- |
118
+ | `APITOGO_API_URL` | Override platform API base URL |
102
119
  | `APITOGO_CLI_PATH` | Local `@lukoweb/apitogo` / doc-tool checkout for MCP spawn |
103
120
 
104
121
  Never commit secrets. Site auth secrets (OIDC, Stripe) belong in the portal **`.env`** as
package/docs/cli/shape.md CHANGED
@@ -16,8 +16,8 @@ Requires the **`apitogo`** CLI (`@lukoweb/apitogo`). If you have not installed i
16
16
  `npx @lukoweb/create-apitogo` installs `@lukoweb/apitogo` into the new project. Then run config via `npx`:
17
17
 
18
18
  ```bash
19
- npx @lukoweb/create-apitogo@latest my-portal --typescript --eslint
20
- cd my-portal
19
+ npx @lukoweb/create-apitogo@latest dev-portal --typescript --eslint
20
+ cd dev-portal
21
21
  npx apitogo config # backend, OpenAPI, pages, plans (apply each immediately)
22
22
  npm run dev # http://localhost:3000
23
23
  ```
package/docs/deploy/apitogo.md CHANGED
@@ -11,7 +11,7 @@ Quick reference:
11
11
  ```bash
12
12
  export APITOGO_API_KEY_ID=apk_...
13
13
  export APITOGO_API_SECRET=...
14
- cd ./my-portal
14
+ cd ./dev-portal
15
15
  apitogo apply --platform-plan free
16
16
  apitogo status
17
17
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lukoweb/apitogo",
3
- "version": "0.1.95",
3
+ "version": "0.1.97",
4
4
  "type": "module",
5
5
  "sideEffects": [
6
6
  "**/*.css",
package/src/vite/config.ts CHANGED
@@ -160,6 +160,9 @@ export async function getViteConfig(
160
160
  server: {
161
161
  middlewareMode: true,
162
162
  open: true,
163
+ fs: {
164
+ allow: [dir, path.dirname(dir)],
165
+ },
163
166
  watch: {
164
167
  ignored: [
165
168
  `${dir}/dist`,
package/src/vite/plugin-offroot-resolve.ts ADDED
@@ -0,0 +1,71 @@
1
+ import path from "node:path";
2
+ import type { Plugin, ResolveIdOptions } from "vite";
3
+ import { getCurrentConfig } from "../config/loader.js";
4
+
5
+ function stripQuery(id: string): string {
6
+ const query = id.indexOf("?");
7
+ return query === -1 ? id : id.slice(0, query);
8
+ }
9
+
10
+ function isInside(parent: string, child: string): boolean {
11
+ const relative = path.relative(path.resolve(parent), path.resolve(child));
12
+ return (
13
+ relative === "" ||
14
+ (!relative.startsWith("..") && !path.isAbsolute(relative))
15
+ );
16
+ }
17
+
18
+ function isBareSpecifier(source: string): boolean {
19
+ return (
20
+ !source.startsWith("\0") &&
21
+ !source.startsWith(".") &&
22
+ !source.startsWith("/") &&
23
+ !path.isAbsolute(source)
24
+ );
25
+ }
26
+
27
+ function isInsideNodeModules(filePath: string): boolean {
28
+ return filePath.split(path.sep).includes("node_modules");
29
+ }
30
+
31
+ /** True when Vite followed a symlink (or glob) to markdown outside the site. */
32
+ export function shouldResolveFromSiteRoot(
33
+ source: string,
34
+ importer: string | undefined,
35
+ rootDir: string,
36
+ ): boolean {
37
+ if (!importer || !isBareSpecifier(source)) {
38
+ return false;
39
+ }
40
+ const importerPath = stripQuery(importer);
41
+ if (isInside(rootDir, importerPath) || isInsideNodeModules(importerPath)) {
42
+ return false;
43
+ }
44
+ return true;
45
+ }
46
+
47
+ /**
48
+ * Linked docs live outside the site (e.g. ../doc/*.md). Vite import-analysis
49
+ * then cannot resolve `@lukoweb/apitogo/components` from that folder.
50
+ * Re-resolve bare imports as if they came from the site package.json.
51
+ */
52
+ export default function viteOffrootResolvePlugin(): Plugin {
53
+ return {
54
+ name: "zudoku-offroot-resolve",
55
+ enforce: "pre",
56
+ async resolveId(
57
+ source: string,
58
+ importer: string | undefined,
59
+ options: ResolveIdOptions,
60
+ ) {
61
+ const rootDir = getCurrentConfig().__meta.rootDir;
62
+ if (!shouldResolveFromSiteRoot(source, importer, rootDir)) {
63
+ return;
64
+ }
65
+ return this.resolve(source, path.join(rootDir, "package.json"), {
66
+ ...options,
67
+ skipSelf: true,
68
+ });
69
+ },
70
+ };
71
+ }
package/src/vite/plugin.ts CHANGED
@@ -16,6 +16,7 @@ import viteMarkdownExportPlugin from "./plugin-markdown-export.js";
16
16
  import viteMdxPlugin from "./plugin-mdx.js";
17
17
  import viteModulesPlugin from "./plugin-modules.js";
18
18
  import { viteNavigationPlugin } from "./plugin-navigation.js";
19
+ import viteOffrootResolvePlugin from "./plugin-offroot-resolve.js";
19
20
  import { viteSearchPlugin } from "./plugin-search.js";
20
21
  import { viteShikiRegisterPlugin } from "./plugin-shiki-register.js";
21
22
  import { viteThemePlugin } from "./plugin-theme.js";
@@ -23,6 +24,7 @@ import { viteThemePlugin } from "./plugin-theme.js";
23
24
  export default function vitePlugin(): PluginOption {
24
25
  return [
25
26
  viteShikiRegisterPlugin(),
27
+ viteOffrootResolvePlugin(),
26
28
  viteConfigReloadPlugin(),
27
29
  viteLocalManifestPlugin(),
28
30
  viteMdxPlugin(),