@lukoweb/apitogo 0.1.95 → 0.1.96
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.
- package/dist/cli/cli.js +593 -404
- package/dist/declarations/cli/platform/helpers/openapi.d.ts +1 -2
- package/dist/declarations/cli/scaffold/discover-openapi-files.d.ts +15 -0
- package/docs/cli/commands.md +43 -42
- package/docs/cli/go-live.md +1 -1
- package/docs/cli/setup.md +46 -29
- package/docs/cli/shape.md +2 -2
- package/docs/deploy/apitogo.md +1 -1
- package/package.json +1 -1
|
@@ -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>;
|
|
@@ -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
|
|
14
|
-
|
|
|
15
|
-
| `init`
|
|
16
|
-
| `config` / `make-config` | Write or update `apitogo.config.json` (interactive or flags)
|
|
17
|
-
| `dev`
|
|
18
|
-
| `build`
|
|
19
|
-
| `check`
|
|
20
|
-
| `project create`
|
|
21
|
-
| `apply`
|
|
22
|
-
| `status`
|
|
23
|
-
| `teardown --yes`
|
|
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
|
|
28
|
-
|
|
|
29
|
-
| `init [dir]` | Named folder; `--install` (default), `--overwrite`, `--json`, `--openapi-search`
|
|
30
|
-
| `config`
|
|
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
|
-
|
|
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
|
|
40
|
-
|
|
|
41
|
-
| `dev`
|
|
42
|
-
| `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
|
|
48
|
-
|
|
|
49
|
-
| `project create --name`
|
|
50
|
-
| `check`
|
|
51
|
-
| `apply`
|
|
52
|
-
| `apply --only <resource>` | Limit to `apihub`, `portal-backend`, or `portal-frontend`
|
|
53
|
-
| `apply --force`
|
|
54
|
-
| `apply --platform-plan`
|
|
55
|
-
| `apply --resume-from`
|
|
56
|
-
| `status`
|
|
57
|
-
| `teardown --yes`
|
|
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
|
|
75
|
-
|
|
|
76
|
-
| `deploy`
|
|
77
|
-
| `preview`
|
|
78
|
-
| `remove`
|
|
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
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
|
|
9
|
-
preview with `apitogo dev`, and publish with `apitogo apply`. Platform
|
|
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
|
-
|
|
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.
|
|
21
|
-
|
|
22
|
-
|
|
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
|
|
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
|
|
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
|
|
42
|
-
cd
|
|
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
|
|
49
|
-
|
|
|
50
|
-
| `--typescript` / `--ts` | TypeScript project
|
|
51
|
-
| `--javascript` / `--js` | JavaScript project
|
|
52
|
-
| `--eslint`
|
|
53
|
-
| `--no-eslint`
|
|
54
|
-
| `--include-examples`
|
|
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
|
-
|
|
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
|
|
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
|
|
82
|
-
| One-off, no project yet
|
|
83
|
-
|
|
|
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
|
|
20
|
-
cd
|
|
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