@politelabs/cabin-cli 0.3.0 → 0.6.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/README.md +8 -7
- package/dist/commands/context.js +79 -9
- package/dist/commands/login.js +141 -36
- package/dist/commands/theme/check.js +3 -2
- package/dist/commands/theme/context.js +38 -0
- package/dist/commands/theme/dev.js +27 -9
- package/dist/commands/theme/init.js +49 -27
- package/dist/commands/theme/pull.js +24 -2
- package/dist/commands/theme/push.js +3 -3
- package/dist/commands/theme/sync.js +24 -2
- package/dist/index.js +3 -1
- package/dist/io/fs.js +45 -4
- package/dist/io/loopback.js +43 -0
- package/dist/io/world.js +9 -1
- package/dist/lib/api.js +60 -25
- package/dist/lib/args.js +6 -2
- package/dist/lib/context.js +68 -0
- package/dist/lib/credentials.js +30 -3
- package/dist/lib/oauth.js +180 -0
- package/dist/lib/scaffold.js +9 -3
- package/dist/lib/theme-files.js +45 -4
- package/package.json +38 -36
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { failureOf } from './api.js';
|
|
3
|
+
/**
|
|
4
|
+
* Signing in through the browser: OAuth 2.1 with Cabin's own client, the
|
|
5
|
+
* authorization code with PKCE, sent back to a loopback address the CLI
|
|
6
|
+
* listens on. The token is the person, on every site they are on, so each
|
|
7
|
+
* request names its site with `Cabin-Site`.
|
|
8
|
+
*/
|
|
9
|
+
/** Cabin CLI, the client every Cabin makes for this tool. */
|
|
10
|
+
export const CLI_CLIENT = 'b9a719b1-9b60-49a0-bd1b-fa4938f836a8';
|
|
11
|
+
/** What the CLI asks to do: work on the person's sites' themes. */
|
|
12
|
+
export const SCOPE = 'themes';
|
|
13
|
+
/** How long to wait for the person to approve in the browser. */
|
|
14
|
+
export const APPROVE_WITHIN_MS = 5 * 60_000;
|
|
15
|
+
/** A sign-in is refreshed when it has less than this left. */
|
|
16
|
+
const REFRESH_MARGIN_MS = 60_000;
|
|
17
|
+
/** The token endpoint refused, in OAuth's own shape (`invalid_grant`…). */
|
|
18
|
+
export class OauthRefused extends Error {
|
|
19
|
+
status;
|
|
20
|
+
code;
|
|
21
|
+
constructor(status, code, message) {
|
|
22
|
+
super(message);
|
|
23
|
+
this.status = status;
|
|
24
|
+
this.code = code;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
export function base64url(bytes) {
|
|
28
|
+
return Buffer.from(bytes).toString('base64url');
|
|
29
|
+
}
|
|
30
|
+
/** A PKCE verifier from random bytes, and its S256 challenge. */
|
|
31
|
+
export function pkce(random) {
|
|
32
|
+
const verifier = base64url(random);
|
|
33
|
+
return {
|
|
34
|
+
verifier,
|
|
35
|
+
challenge: createHash('sha256').update(verifier).digest('base64url'),
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
/** Where to send the person to approve the CLI. */
|
|
39
|
+
export function authorizeUrl(host, given) {
|
|
40
|
+
const query = new URLSearchParams({
|
|
41
|
+
client_id: CLI_CLIENT,
|
|
42
|
+
redirect_uri: given.redirectUri,
|
|
43
|
+
response_type: 'code',
|
|
44
|
+
scope: SCOPE,
|
|
45
|
+
state: given.state,
|
|
46
|
+
code_challenge: given.challenge,
|
|
47
|
+
code_challenge_method: 'S256',
|
|
48
|
+
});
|
|
49
|
+
return `${host}/oauth/authorize?${query.toString()}`;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* What the browser came back with: a code, or why there is none. A state
|
|
53
|
+
* that isn't the one sent is another sign-in's, and is refused.
|
|
54
|
+
*/
|
|
55
|
+
export function readCallback(url, state) {
|
|
56
|
+
if (url.searchParams.get('state') !== state) {
|
|
57
|
+
return {
|
|
58
|
+
refused: 'The browser came back from another sign-in. Run cabin login again.',
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
const error = url.searchParams.get('error');
|
|
62
|
+
if (error === 'access_denied') {
|
|
63
|
+
return { refused: 'You cancelled signing in.' };
|
|
64
|
+
}
|
|
65
|
+
if (error !== null) {
|
|
66
|
+
return {
|
|
67
|
+
refused: `Cabin refused to sign you in: ${url.searchParams.get('error_description') ?? error}`,
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
const code = url.searchParams.get('code');
|
|
71
|
+
return code === null || code === ''
|
|
72
|
+
? {
|
|
73
|
+
refused: 'The browser came back without a code. Run cabin login again.',
|
|
74
|
+
}
|
|
75
|
+
: { code };
|
|
76
|
+
}
|
|
77
|
+
/** The page the browser is shown when it comes back to the CLI: what the CLI made of it. */
|
|
78
|
+
export function callbackPage(read) {
|
|
79
|
+
const words = 'code' in read
|
|
80
|
+
? 'Signed in to Cabin. You can close this tab and go back to the terminal.'
|
|
81
|
+
: `${read.refused} You can close this tab.`;
|
|
82
|
+
return `<!doctype html><html lang="en"><meta charset="utf-8"><title>Cabin CLI</title><body style="font:16px/1.5 system-ui,sans-serif;margin:4rem auto;max-width:32rem;padding:0 1rem"><p>${escapeHtml(words)}</p></body></html>`;
|
|
83
|
+
}
|
|
84
|
+
/** Text made safe to put in a page: a refusal can carry words from the address. */
|
|
85
|
+
function escapeHtml(text) {
|
|
86
|
+
return text.replace(/[&<>"']/g, (character) => ({
|
|
87
|
+
'&': '&',
|
|
88
|
+
'<': '<',
|
|
89
|
+
'>': '>',
|
|
90
|
+
'"': '"',
|
|
91
|
+
"'": ''',
|
|
92
|
+
})[character] ?? character);
|
|
93
|
+
}
|
|
94
|
+
/** Read the token endpoint's answer, or null when it isn't one. */
|
|
95
|
+
export function tokensFrom(answer, now) {
|
|
96
|
+
const given = answer;
|
|
97
|
+
if (typeof given?.access_token !== 'string' ||
|
|
98
|
+
typeof given.refresh_token !== 'string' ||
|
|
99
|
+
typeof given.expires_in !== 'number') {
|
|
100
|
+
return null;
|
|
101
|
+
}
|
|
102
|
+
return {
|
|
103
|
+
accessToken: given.access_token,
|
|
104
|
+
refreshToken: given.refresh_token,
|
|
105
|
+
expiresAt: new Date(now + given.expires_in * 1000).toISOString(),
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
/** Whether a sign-in's access token has run out, or nearly. */
|
|
109
|
+
export function isDue(expiresAt, now) {
|
|
110
|
+
const at = Date.parse(expiresAt);
|
|
111
|
+
return Number.isNaN(at) || at - now < REFRESH_MARGIN_MS;
|
|
112
|
+
}
|
|
113
|
+
/** Trade the code the browser came back with for tokens. */
|
|
114
|
+
export function exchangeCode(host, fetchFn, given, now) {
|
|
115
|
+
return tokenRequest(host, fetchFn, {
|
|
116
|
+
grant_type: 'authorization_code',
|
|
117
|
+
client_id: CLI_CLIENT,
|
|
118
|
+
code: given.code,
|
|
119
|
+
redirect_uri: given.redirectUri,
|
|
120
|
+
code_verifier: given.verifier,
|
|
121
|
+
}, now);
|
|
122
|
+
}
|
|
123
|
+
/** Trade a refresh token for new tokens. Cabin ends the old one. */
|
|
124
|
+
export function refreshTokens(host, fetchFn, refreshToken, now) {
|
|
125
|
+
return tokenRequest(host, fetchFn, {
|
|
126
|
+
grant_type: 'refresh_token',
|
|
127
|
+
client_id: CLI_CLIENT,
|
|
128
|
+
refresh_token: refreshToken,
|
|
129
|
+
scope: SCOPE,
|
|
130
|
+
}, now);
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* Whether a host takes signing in through the browser: an older Cabin has
|
|
134
|
+
* no `/v1/sites`, and answers 404 where a newer one asks for a token.
|
|
135
|
+
*/
|
|
136
|
+
export async function takesBrowserSignIn(host, fetchFn) {
|
|
137
|
+
let response;
|
|
138
|
+
try {
|
|
139
|
+
response = await fetchFn(`${host}/v1/sites`, {
|
|
140
|
+
headers: { Accept: 'application/json' },
|
|
141
|
+
});
|
|
142
|
+
}
|
|
143
|
+
catch {
|
|
144
|
+
throw failureOf(0, null);
|
|
145
|
+
}
|
|
146
|
+
await response.body?.cancel();
|
|
147
|
+
return response.status !== 404;
|
|
148
|
+
}
|
|
149
|
+
async function tokenRequest(host, fetchFn, form, now) {
|
|
150
|
+
let response;
|
|
151
|
+
try {
|
|
152
|
+
response = await fetchFn(`${host}/oauth/token`, {
|
|
153
|
+
method: 'POST',
|
|
154
|
+
headers: {
|
|
155
|
+
Accept: 'application/json',
|
|
156
|
+
'Content-Type': 'application/x-www-form-urlencoded',
|
|
157
|
+
},
|
|
158
|
+
body: new URLSearchParams(form).toString(),
|
|
159
|
+
});
|
|
160
|
+
}
|
|
161
|
+
catch {
|
|
162
|
+
throw failureOf(0, null);
|
|
163
|
+
}
|
|
164
|
+
let answer = null;
|
|
165
|
+
try {
|
|
166
|
+
answer = await response.json();
|
|
167
|
+
}
|
|
168
|
+
catch {
|
|
169
|
+
answer = null;
|
|
170
|
+
}
|
|
171
|
+
const tokens = response.ok ? tokensFrom(answer, now) : null;
|
|
172
|
+
if (tokens === null) {
|
|
173
|
+
const given = answer;
|
|
174
|
+
const code = typeof given?.error === 'string' ? given.error : 'http_error';
|
|
175
|
+
throw new OauthRefused(response.status, code, typeof given?.error_description === 'string'
|
|
176
|
+
? given.error_description
|
|
177
|
+
: `The server answered ${response.status}.`);
|
|
178
|
+
}
|
|
179
|
+
return tokens;
|
|
180
|
+
}
|
package/dist/lib/scaffold.js
CHANGED
|
@@ -17,7 +17,10 @@ export function packageJson(key) {
|
|
|
17
17
|
/**
|
|
18
18
|
* The stylesheet's source with Tailwind: its theme and utilities, not its
|
|
19
19
|
* preflight, so the stylesheet as pulled keeps its look, inside the base
|
|
20
|
-
* layer so utilities written in templates win.
|
|
20
|
+
* layer so utilities written in templates win. Tailwind's classes are
|
|
21
|
+
* prefixed (`tw:flex`): it scans the templates for class names, and one
|
|
22
|
+
* of the theme's own called `container` or `hidden` would otherwise pick
|
|
23
|
+
* up Tailwind's rules without anyone asking.
|
|
21
24
|
*/
|
|
22
25
|
export function tailwindSource(pulledCss) {
|
|
23
26
|
return [
|
|
@@ -26,11 +29,14 @@ export function tailwindSource(pulledCss) {
|
|
|
26
29
|
" utilities are included; its preflight isn't, so the styles below stay as",
|
|
27
30
|
" they were. Cabin sets the site's colours and fonts as CSS variables:",
|
|
28
31
|
' --cabin-accent, --cabin-background, --cabin-text, --cabin-font-body, ...',
|
|
32
|
+
" Tailwind's classes carry the prefix tw: (tw:flex, tw:md:grid), so a class",
|
|
33
|
+
" of your own named like one of Tailwind's (container, hidden, flex) is",
|
|
34
|
+
' only ever yours. Take prefix(tw) off both imports to write them bare.',
|
|
29
35
|
" The built file has to pass Cabin's stylesheet rules: no @import, no url()",
|
|
30
36
|
' to another host, no data: URLs, and at most 256 KB. */',
|
|
31
37
|
'@layer theme, base, components, utilities;',
|
|
32
|
-
'@import "tailwindcss/theme.css" layer(theme);',
|
|
33
|
-
'@import "tailwindcss/utilities.css" layer(utilities);',
|
|
38
|
+
'@import "tailwindcss/theme.css" layer(theme) prefix(tw);',
|
|
39
|
+
'@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);',
|
|
34
40
|
'@source "../templates";',
|
|
35
41
|
'',
|
|
36
42
|
'@layer base {',
|
package/dist/lib/theme-files.js
CHANGED
|
@@ -1,10 +1,51 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* What a theme may hold, as Cabin's `ThemeFileRules` says it: the manifest,
|
|
3
|
-
* the stylesheet, templates under `templates/` at any depth,
|
|
4
|
-
* under `patterns/`,
|
|
5
|
-
*
|
|
3
|
+
* the stylesheet, templates under `templates/` at any depth, patterns
|
|
4
|
+
* under `patterns/`, and scripts and drawings (`.js`, `.svg`) under
|
|
5
|
+
* `assets/` at any depth, named in lower case, all as text. A copy of the server's
|
|
6
|
+
* rule: the server is the judge, and this only says what is worth sending.
|
|
6
7
|
*/
|
|
7
|
-
export const THEME_PATH = /^(theme\.json|theme\.css|templates\/[a-z0-9_-]+(\/[a-z0-9_-]+)*\.twig|patterns\/[a-z0-9-]+\.json)$/;
|
|
8
|
+
export const THEME_PATH = /^(theme\.json|theme\.css|templates\/[a-z0-9_-]+(\/[a-z0-9_-]+)*\.twig|patterns\/[a-z0-9-]+\.json|assets\/[a-z0-9_-]+(\/[a-z0-9_-]+)*\.(js|svg))$/;
|
|
9
|
+
/**
|
|
10
|
+
* A theme's pictures: PNG, JPEG, WebP, GIF and AVIF under `assets/`. They
|
|
11
|
+
* aren't text, so they travel beside the files, as `binaries`. A copy of
|
|
12
|
+
* the server's rule, as the path above is.
|
|
13
|
+
*/
|
|
14
|
+
export const PICTURE_PATH = /^assets\/[a-z0-9_-]+(\/[a-z0-9_-]+)*\.(png|jpg|jpeg|webp|gif|avif)$/;
|
|
15
|
+
/** Whether a path, relative to the theme's folder, is a picture's. */
|
|
16
|
+
export function isPicturePath(path) {
|
|
17
|
+
return PICTURE_PATH.test(path);
|
|
18
|
+
}
|
|
19
|
+
/** Whether a path is one that is synced at all: a theme's file, or a picture. */
|
|
20
|
+
export function isSynced(path) {
|
|
21
|
+
return isThemePath(path) || isPicturePath(path);
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* What names a stored picture on the site: its hash and its kind, since
|
|
25
|
+
* the site keeps a file under both.
|
|
26
|
+
*/
|
|
27
|
+
export function blobKey(path, hash) {
|
|
28
|
+
return `${hash}.${path.slice(path.lastIndexOf('.') + 1)}`;
|
|
29
|
+
}
|
|
30
|
+
/** The blobs the site holds, from the pictures it says a theme has. */
|
|
31
|
+
export function heldBlobs(held) {
|
|
32
|
+
return new Set(Object.entries(held ?? {}).map(([path, picture]) => blobKey(path, picture.hash)));
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* What to send for the folder's pictures: only the bytes of the ones the
|
|
36
|
+
* site doesn't hold yet, and the hash of every other, so a picture that
|
|
37
|
+
* hasn't changed never travels twice.
|
|
38
|
+
*/
|
|
39
|
+
export function binariesFor(local, held) {
|
|
40
|
+
const binaries = {};
|
|
41
|
+
for (const path of Object.keys(local).sort()) {
|
|
42
|
+
const picture = local[path];
|
|
43
|
+
binaries[path] = held.has(blobKey(path, picture.hash))
|
|
44
|
+
? { hash: picture.hash }
|
|
45
|
+
: picture.base64;
|
|
46
|
+
}
|
|
47
|
+
return binaries;
|
|
48
|
+
}
|
|
8
49
|
/** The files every theme has to hold. */
|
|
9
50
|
export const REQUIRED = [
|
|
10
51
|
'theme.json',
|
package/package.json
CHANGED
|
@@ -1,37 +1,39 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
"
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
}
|
|
2
|
+
"name": "@politelabs/cabin-cli",
|
|
3
|
+
"version": "0.6.0",
|
|
4
|
+
"description": "Develop a Cabin site theme locally: init, dev, push, pull, check, publish.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "https://github.com/PoliteLabs/cabin-cli.git"
|
|
9
|
+
},
|
|
10
|
+
"type": "module",
|
|
11
|
+
"bin": {
|
|
12
|
+
"cabin": "dist/index.js"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"dist",
|
|
16
|
+
"README.md"
|
|
17
|
+
],
|
|
18
|
+
"engines": {
|
|
19
|
+
"node": ">=22.12"
|
|
20
|
+
},
|
|
21
|
+
"publishConfig": {
|
|
22
|
+
"access": "public"
|
|
23
|
+
},
|
|
24
|
+
"scripts": {
|
|
25
|
+
"build": "tsc -p tsconfig.build.json",
|
|
26
|
+
"check": "biome check .",
|
|
27
|
+
"check:fix": "biome check --write .",
|
|
28
|
+
"types:check": "tsc --noEmit",
|
|
29
|
+
"test": "vitest run",
|
|
30
|
+
"prepublishOnly": "pnpm build"
|
|
31
|
+
},
|
|
32
|
+
"devDependencies": {
|
|
33
|
+
"@biomejs/biome": "2.2.4",
|
|
34
|
+
"@types/node": "^22.13.5",
|
|
35
|
+
"typescript": "^5.9.3",
|
|
36
|
+
"vitest": "^3.2.4"
|
|
37
|
+
},
|
|
38
|
+
"packageManager": "pnpm@12.15.0"
|
|
39
|
+
}
|