@kanorio/cli 0.0.0-stage → 1.0.0
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/LICENSE +21 -0
- package/README.md +50 -2
- package/dist/args.js +119 -0
- package/dist/bin.js +46 -0
- package/dist/client.js +107 -0
- package/dist/commands.js +469 -0
- package/dist/config.js +63 -0
- package/dist/help.js +83 -0
- package/dist/output.js +111 -0
- package/dist/types-codegen.js +367 -0
- package/package.json +46 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kanorio, Inc.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,51 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @kanorio/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`kanorio` is a thin command-line wrapper around the Kanorio Management API (`https://app.kanorio.com/api/v1`). It has no business logic of its own and no third-party dependencies; the list of operations and their inputs and outputs follow the [OpenAPI document](https://app.kanorio.com/api/v1/openapi.json).
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install -g @kanorio/cli # or: npx @kanorio/cli --help
|
|
7
|
+
kanorio --help
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Requires Node.js 20 or later.
|
|
11
|
+
|
|
12
|
+
## Sign in
|
|
13
|
+
|
|
14
|
+
1. Create a personal access token (`knr_pat_…`) at <https://app.kanorio.com/account/api-access>.
|
|
15
|
+
2. Run `kanorio login` (prompts without echo) or `kanorio login --token knr_pat_…`. The token is stored in `~/.config/kanorio/config.json` (file mode 0600, directory 0700; `XDG_CONFIG_HOME` is respected).
|
|
16
|
+
3. In CI and scripts, set `KANORIO_TOKEN` instead; it takes precedence over the config file.
|
|
17
|
+
|
|
18
|
+
## Common commands
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
kanorio sites list
|
|
22
|
+
kanorio sites create --name "Sunny Bakery" --locale en --timezone Asia/Taipei --profile local_food
|
|
23
|
+
kanorio sites create --brief brief.json && kanorio jobs get <jobId>
|
|
24
|
+
kanorio settings update <siteId> --brand-color "#C8553D" --corner-radius soft
|
|
25
|
+
kanorio pages list <siteId>
|
|
26
|
+
kanorio pages create <siteId> --title "About" --slug /about
|
|
27
|
+
kanorio pages get <siteId> <pageId> --json > page.json
|
|
28
|
+
kanorio pages replace-sections <siteId> <pageId> --file sections.json
|
|
29
|
+
kanorio globals replace-header <siteId> --file header.json
|
|
30
|
+
kanorio publish <siteId> --subdomain sunny-bakery
|
|
31
|
+
kanorio domains bind <siteId> www.example.com example.com
|
|
32
|
+
kanorio types --site https://example.com --out kanorio.d.ts # TypeScript types for the site's collections
|
|
33
|
+
kanorio doctor --site <siteId> # check a self-hosted front end against the site
|
|
34
|
+
kanorio keys create --site <siteId> --write-env .env.local # issue a server key without printing it
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`kanorio --help` lists every command with its capability domain.
|
|
38
|
+
|
|
39
|
+
### Server keys
|
|
40
|
+
|
|
41
|
+
`keys create` issues a **server key** (`knr_sa_…`) so the server of a self-hosted front end can act on behalf of a visitor: submit a form, complete a customer sign-in, report an AI crawler hit. A server key cannot call the Management API. `--write-env <file>` writes `KANORIO_SERVER_KEY=…` into that file (created with mode 0600) and does not print the key; if the line already exists, add `--force` to replace it. The CLI warns when the file is not ignored by git. Without `--write-env` the key is printed once. To rotate: run the command again, deploy the new key, then revoke the old one under Site settings > Developer.
|
|
42
|
+
|
|
43
|
+
### Output and errors
|
|
44
|
+
|
|
45
|
+
`--json` makes both stdout and stderr JSON. Errors are printed as `<CODE> (HTTP <status>): <message>` with exit code 1; usage errors exit with 2. `CONFLICT` means the page changed since you read it: run `pages get` again for the current `updatedAt` and resend. The same applies to `globals *` with `contentUpdatedAt`.
|
|
46
|
+
|
|
47
|
+
## Documentation and support
|
|
48
|
+
|
|
49
|
+
- Documentation: <https://kanorio.com/en/developers/cli>
|
|
50
|
+
- Changes: [CHANGELOG.md](./CHANGELOG.md). The package follows semantic versioning and is released together with `@kanorio/sdk` and `@kanorio/elements` under one version number.
|
|
51
|
+
- Questions and bug reports: <support@kanorio.com>. To report a security issue, write to <security@kanorio.com> instead of opening a public report.
|
package/dist/args.js
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 參數解析:只用 node:util parseArgs,不引入第三方。
|
|
3
|
+
* 所有旗標全域宣告(parseArgs 不支援子命令層級宣告),各命令自己決定要讀哪些。
|
|
4
|
+
*/
|
|
5
|
+
import { parseArgs } from "node:util";
|
|
6
|
+
/** 由兩段組成的子命令;其餘命令只有一段 */
|
|
7
|
+
const TWO_PART_COMMANDS = new Set(["sites", "pages", "domains", "sections", "jobs", "settings", "globals", "media", "keys"]);
|
|
8
|
+
export class UsageError extends Error {
|
|
9
|
+
exitCode = 2;
|
|
10
|
+
}
|
|
11
|
+
function rawParse(argv) {
|
|
12
|
+
try {
|
|
13
|
+
return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true, strict: true });
|
|
14
|
+
}
|
|
15
|
+
catch (error) {
|
|
16
|
+
throw new UsageError(error instanceof Error ? error.message : String(error));
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
export function parseCliArgs(argv) {
|
|
20
|
+
const parsed = rawParse(argv);
|
|
21
|
+
const values = parsed.values;
|
|
22
|
+
const positionals = [...parsed.positionals];
|
|
23
|
+
const command = [];
|
|
24
|
+
const head = positionals.shift();
|
|
25
|
+
if (head) {
|
|
26
|
+
command.push(head);
|
|
27
|
+
if (TWO_PART_COMMANDS.has(head)) {
|
|
28
|
+
const sub = positionals.shift();
|
|
29
|
+
if (sub)
|
|
30
|
+
command.push(sub);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
return {
|
|
34
|
+
command,
|
|
35
|
+
positionals,
|
|
36
|
+
flags: {
|
|
37
|
+
json: values.json === true,
|
|
38
|
+
help: values.help === true,
|
|
39
|
+
version: values.version === true,
|
|
40
|
+
hidden: values.hidden === true,
|
|
41
|
+
visible: values.visible === true,
|
|
42
|
+
profile: values.profile,
|
|
43
|
+
description: values.description,
|
|
44
|
+
brandColor: values["brand-color"],
|
|
45
|
+
brandColorDark: values["brand-color-dark"],
|
|
46
|
+
cornerRadius: values["corner-radius"],
|
|
47
|
+
colorScheme: values["color-scheme"],
|
|
48
|
+
density: values.density,
|
|
49
|
+
currency: values.currency,
|
|
50
|
+
url: values.url,
|
|
51
|
+
query: values.query,
|
|
52
|
+
orientation: values.orientation,
|
|
53
|
+
provider: values.provider,
|
|
54
|
+
max: values.max,
|
|
55
|
+
purpose: values.purpose,
|
|
56
|
+
uploadToken: values["upload-token"],
|
|
57
|
+
stockId: values["stock-id"],
|
|
58
|
+
api: values.api,
|
|
59
|
+
token: values.token,
|
|
60
|
+
file: values.file,
|
|
61
|
+
name: values.name,
|
|
62
|
+
locale: values.locale,
|
|
63
|
+
timezone: values.timezone,
|
|
64
|
+
brief: values.brief,
|
|
65
|
+
subdomain: values.subdomain,
|
|
66
|
+
title: values.title,
|
|
67
|
+
slug: values.slug,
|
|
68
|
+
detail: values.detail,
|
|
69
|
+
site: values.site,
|
|
70
|
+
ifUnmodifiedSince: values["if-unmodified-since"],
|
|
71
|
+
out: values.out,
|
|
72
|
+
switching: values.switching === true,
|
|
73
|
+
writeEnv: values["write-env"],
|
|
74
|
+
keyName: values["key-name"],
|
|
75
|
+
force: values.force === true,
|
|
76
|
+
},
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
const OPTIONS = {
|
|
80
|
+
json: { type: "boolean", default: false },
|
|
81
|
+
help: { type: "boolean", short: "h", default: false },
|
|
82
|
+
version: { type: "boolean", short: "v", default: false },
|
|
83
|
+
hidden: { type: "boolean", default: false },
|
|
84
|
+
visible: { type: "boolean", default: false },
|
|
85
|
+
profile: { type: "string" },
|
|
86
|
+
description: { type: "string" },
|
|
87
|
+
"brand-color": { type: "string" },
|
|
88
|
+
"brand-color-dark": { type: "string" },
|
|
89
|
+
"corner-radius": { type: "string" },
|
|
90
|
+
"color-scheme": { type: "string" },
|
|
91
|
+
density: { type: "string" },
|
|
92
|
+
currency: { type: "string" },
|
|
93
|
+
url: { type: "string" },
|
|
94
|
+
query: { type: "string", short: "q" },
|
|
95
|
+
orientation: { type: "string" },
|
|
96
|
+
provider: { type: "string" },
|
|
97
|
+
max: { type: "string" },
|
|
98
|
+
purpose: { type: "string" },
|
|
99
|
+
"upload-token": { type: "string" },
|
|
100
|
+
"stock-id": { type: "string" },
|
|
101
|
+
api: { type: "string" },
|
|
102
|
+
token: { type: "string" },
|
|
103
|
+
file: { type: "string", short: "f" },
|
|
104
|
+
name: { type: "string" },
|
|
105
|
+
locale: { type: "string" },
|
|
106
|
+
timezone: { type: "string" },
|
|
107
|
+
brief: { type: "string" },
|
|
108
|
+
subdomain: { type: "string" },
|
|
109
|
+
title: { type: "string" },
|
|
110
|
+
slug: { type: "string" },
|
|
111
|
+
detail: { type: "string" },
|
|
112
|
+
site: { type: "string" },
|
|
113
|
+
"if-unmodified-since": { type: "string" },
|
|
114
|
+
out: { type: "string", short: "o" },
|
|
115
|
+
switching: { type: "boolean", default: false },
|
|
116
|
+
"write-env": { type: "string" },
|
|
117
|
+
"key-name": { type: "string" },
|
|
118
|
+
force: { type: "boolean", default: false },
|
|
119
|
+
};
|
package/dist/bin.js
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { createRequire } from "node:module";
|
|
3
|
+
import { parseCliArgs, UsageError } from "./args.js";
|
|
4
|
+
import { formatDeprecationWarning } from "./client.js";
|
|
5
|
+
import { resolveCommand } from "./commands.js";
|
|
6
|
+
import { HELP } from "./help.js";
|
|
7
|
+
import { formatError, formatResult } from "./output.js";
|
|
8
|
+
const require = createRequire(import.meta.url);
|
|
9
|
+
const { version } = require("../package.json");
|
|
10
|
+
async function main(argv) {
|
|
11
|
+
let json = argv.includes("--json");
|
|
12
|
+
try {
|
|
13
|
+
const cli = parseCliArgs(argv);
|
|
14
|
+
json = cli.flags.json;
|
|
15
|
+
if (cli.flags.version) {
|
|
16
|
+
process.stdout.write(`${version}\n`);
|
|
17
|
+
return 0;
|
|
18
|
+
}
|
|
19
|
+
if (cli.flags.help || cli.command.length === 0) {
|
|
20
|
+
process.stdout.write(HELP);
|
|
21
|
+
return cli.command.length === 0 && !cli.flags.help ? 2 : 0;
|
|
22
|
+
}
|
|
23
|
+
const handler = resolveCommand(cli.command);
|
|
24
|
+
if (!handler)
|
|
25
|
+
throw new UsageError(`Unknown command "${cli.command.join(" ")}".`);
|
|
26
|
+
const result = await handler(cli, {
|
|
27
|
+
env: process.env,
|
|
28
|
+
userAgent: `kanorio-cli/${version}`,
|
|
29
|
+
// 淘汰警告走 stderr:--json 的 stdout 仍是乾淨的 JSON
|
|
30
|
+
onDeprecation: (notice) => process.stderr.write(`${formatDeprecationWarning(notice)}\n`),
|
|
31
|
+
});
|
|
32
|
+
process.stdout.write(`${formatResult(result, json)}\n`);
|
|
33
|
+
return 0;
|
|
34
|
+
}
|
|
35
|
+
catch (error) {
|
|
36
|
+
const { text, exitCode } = formatError(error, json);
|
|
37
|
+
process.stderr.write(`${text}\n`);
|
|
38
|
+
return exitCode;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
main(process.argv.slice(2)).then((code) => {
|
|
42
|
+
process.exitCode = code;
|
|
43
|
+
}, (error) => {
|
|
44
|
+
process.stderr.write(`${formatError(error, false).text}\n`);
|
|
45
|
+
process.exitCode = 1;
|
|
46
|
+
});
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* REST 薄包裝:組 URL、帶 bearer、解 JSON、把 `{ error: { code, message, details } }` 轉成 ApiError。
|
|
3
|
+
* 不含任何業務邏輯;伺服端怎麼回就怎麼給。
|
|
4
|
+
*/
|
|
5
|
+
export function isErrorEnvelope(value) {
|
|
6
|
+
if (typeof value !== "object" || value === null)
|
|
7
|
+
return false;
|
|
8
|
+
const error = value.error;
|
|
9
|
+
if (typeof error !== "object" || error === null)
|
|
10
|
+
return false;
|
|
11
|
+
const { code, message } = error;
|
|
12
|
+
return typeof code === "string" && typeof message === "string";
|
|
13
|
+
}
|
|
14
|
+
export class ApiError extends Error {
|
|
15
|
+
code;
|
|
16
|
+
status;
|
|
17
|
+
details;
|
|
18
|
+
retryAfter;
|
|
19
|
+
exitCode = 1;
|
|
20
|
+
constructor(code, status, message, details, retryAfter) {
|
|
21
|
+
super(message);
|
|
22
|
+
this.code = code;
|
|
23
|
+
this.status = status;
|
|
24
|
+
this.details = details;
|
|
25
|
+
this.retryAfter = retryAfter;
|
|
26
|
+
this.name = "ApiError";
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
/** 非 JSON/非封包的回應(例如 Cloudflare 擋下、代理錯誤)也要能印出 code */
|
|
30
|
+
export function toApiError(status, body, retryAfterHeader) {
|
|
31
|
+
const retryAfter = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : undefined;
|
|
32
|
+
if (isErrorEnvelope(body)) {
|
|
33
|
+
return new ApiError(body.error.code, status, body.error.message, body.error.details, retryAfter);
|
|
34
|
+
}
|
|
35
|
+
const code = status === 401 ? "UNAUTHORIZED" : status === 404 ? "NOT_FOUND" : status >= 500 ? "UPSTREAM_ERROR" : "HTTP_ERROR";
|
|
36
|
+
const text = typeof body === "string" ? body.slice(0, 200) : "";
|
|
37
|
+
return new ApiError(code, status, text || `Request failed with HTTP ${status}.`, undefined, retryAfter);
|
|
38
|
+
}
|
|
39
|
+
export function parseDeprecation(headers, method, path) {
|
|
40
|
+
if (!headers.has("deprecation"))
|
|
41
|
+
return null;
|
|
42
|
+
const link = headers.get("link") ?? "";
|
|
43
|
+
const rel = (name) => {
|
|
44
|
+
const match = link.match(new RegExp(`<([^>]+)>;\\s*rel="${name}"`));
|
|
45
|
+
return match?.[1] ?? null;
|
|
46
|
+
};
|
|
47
|
+
return { method, path, sunset: headers.get("sunset"), successor: rel("successor-version"), policy: rel("deprecation") };
|
|
48
|
+
}
|
|
49
|
+
export function formatDeprecationWarning(notice) {
|
|
50
|
+
const parts = [`warning: ${notice.method} ${notice.path} is deprecated`];
|
|
51
|
+
if (notice.sunset)
|
|
52
|
+
parts.push(`and will be removed after ${notice.sunset}`);
|
|
53
|
+
let text = parts.join(" ");
|
|
54
|
+
if (notice.successor)
|
|
55
|
+
text += `; use ${notice.successor}`;
|
|
56
|
+
if (notice.policy)
|
|
57
|
+
text += ` (${notice.policy})`;
|
|
58
|
+
return text;
|
|
59
|
+
}
|
|
60
|
+
export function buildUrl(apiUrl, path, query) {
|
|
61
|
+
const url = new URL(`${apiUrl}/api/v1${path.startsWith("/") ? path : `/${path}`}`);
|
|
62
|
+
for (const [key, value] of Object.entries(query ?? {})) {
|
|
63
|
+
if (value === undefined)
|
|
64
|
+
continue;
|
|
65
|
+
if (Array.isArray(value)) {
|
|
66
|
+
if (value.length > 0)
|
|
67
|
+
url.searchParams.set(key, value.join(","));
|
|
68
|
+
}
|
|
69
|
+
else {
|
|
70
|
+
url.searchParams.set(key, value);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
return url.toString();
|
|
74
|
+
}
|
|
75
|
+
export async function request(options) {
|
|
76
|
+
const fetchImpl = options.fetchImpl ?? fetch;
|
|
77
|
+
const headers = {
|
|
78
|
+
authorization: `Bearer ${options.token}`,
|
|
79
|
+
accept: "application/json",
|
|
80
|
+
"user-agent": options.userAgent ?? "kanorio-cli",
|
|
81
|
+
};
|
|
82
|
+
const init = { method: options.method, headers };
|
|
83
|
+
if (options.body !== undefined) {
|
|
84
|
+
headers["content-type"] = "application/json";
|
|
85
|
+
init.body = JSON.stringify(options.body);
|
|
86
|
+
}
|
|
87
|
+
const res = await fetchImpl(buildUrl(options.apiUrl, options.path, options.query), init);
|
|
88
|
+
const deprecation = parseDeprecation(res.headers, options.method, options.path);
|
|
89
|
+
if (deprecation)
|
|
90
|
+
options.onDeprecation?.(deprecation);
|
|
91
|
+
const text = await res.text();
|
|
92
|
+
let body = text;
|
|
93
|
+
if (text) {
|
|
94
|
+
try {
|
|
95
|
+
body = JSON.parse(text);
|
|
96
|
+
}
|
|
97
|
+
catch {
|
|
98
|
+
body = text;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
else {
|
|
102
|
+
body = null;
|
|
103
|
+
}
|
|
104
|
+
if (!res.ok)
|
|
105
|
+
throw toApiError(res.status, body, res.headers.get("retry-after"));
|
|
106
|
+
return body;
|
|
107
|
+
}
|