@freeappstore/cli 0.4.14 → 0.4.15
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 +210 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -33,16 +33,95 @@ Live in 30 seconds at `https://my-app.freeappstore.online`.
|
|
|
33
33
|
| `fas logout` | Clear the cached session. |
|
|
34
34
|
| `fas whoami` | Print the currently signed-in GitHub login. |
|
|
35
35
|
| `fas doctor` | Health check — Node version, git, pnpm, config, signed-in state, API reachability. |
|
|
36
|
-
| `fas init <app-id
|
|
37
|
-
| `fas check
|
|
36
|
+
| `fas init <app-id>` | Scaffold a new free app or game from a platform template. Replaces `APPNAME` placeholders, runs `git init`, makes the first commit. |
|
|
37
|
+
| `fas check` | Run compliance checks (no-tracking, brand fonts, manifest, bundle size). Exits non-zero on hard failures. |
|
|
38
38
|
| `fas publish` | Provisions repo + hosting route + storefront entry, injects `deploy.yml` if missing, then prints `git remote add` and `git push` instructions. Auto-runs `fas check` first. |
|
|
39
|
-
| `fas list` (alias `fas ls`) | List apps you
|
|
40
|
-
| `fas logs <app-id>` | Tail
|
|
39
|
+
| `fas list` (alias `fas ls`) | List apps and games you have published. `--json` for scripting, `-v` for recent commits. |
|
|
40
|
+
| `fas logs <app-id>` | Tail live deployment logs for an app's Cloudflare Pages project. |
|
|
41
|
+
| `fas secret set\|list\|rm` | Manage server-side encrypted API keys for an app. |
|
|
42
|
+
| `fas proxy allow\|list\|deny` | Manage the URL allowlist for the per-app secret-injecting proxy. |
|
|
43
|
+
| `fas screencheck` | Build the app and run a headless browser at every reference viewport to verify the layout fits without scrolling. |
|
|
44
|
+
| `fas quality [app-id]` | Show the VCQA code quality report (score + grade) for an app. |
|
|
41
45
|
|
|
42
|
-
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
### `fas login`
|
|
49
|
+
|
|
50
|
+
Sign in with GitHub via the device-authorization flow. Opens a browser to authorize the CLI, then exchanges the GitHub token for a platform session token. Both are persisted to `~/.fas/config.json` (mode `0600`).
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
fas login
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### `fas logout`
|
|
57
|
+
|
|
58
|
+
Clear the cached GitHub access token and platform session token.
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
fas logout
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### `fas whoami`
|
|
65
|
+
|
|
66
|
+
Print the GitHub login of the currently signed-in user. Exits non-zero if not authenticated.
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
fas whoami
|
|
70
|
+
# @yourname
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### `fas doctor`
|
|
74
|
+
|
|
75
|
+
Run local health checks: Node version, git, pnpm, config file, signed-in state, and API reachability.
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
fas doctor
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### `fas init <app-id>`
|
|
82
|
+
|
|
83
|
+
Scaffold a new free app or game from a platform template. Clones the template repo, substitutes all `APPNAME` placeholders with the given id, and creates the first git commit.
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
fas init my-app # default: standalone template
|
|
87
|
+
fas init my-app --template connected # uses platform backend (KV, rooms, etc.)
|
|
88
|
+
fas init asteroids --template game-canvas # HTML5 canvas game template
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
| Flag | Purpose |
|
|
92
|
+
|---|---|
|
|
93
|
+
| `-t, --template <name>` | Template to use. Choices: `standalone`, `connected`, `game-canvas`, `game-grid`, `game-3d`. Default: `standalone`. |
|
|
94
|
+
|
|
95
|
+
### `fas check`
|
|
96
|
+
|
|
97
|
+
Run compliance checks against the app in the current directory (or `--dir`). Checks include: no tracking SDKs, brand fonts present, no brand token overrides, PWA manifest valid, bundle size under limit, and no leftover `APPNAME` placeholders. Exits non-zero on hard failures.
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
fas check # check cwd
|
|
101
|
+
fas check --dir ../my-app
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
| Flag | Purpose |
|
|
105
|
+
|---|---|
|
|
106
|
+
| `--dir <path>` | Repo directory to check. Defaults to cwd. |
|
|
107
|
+
|
|
108
|
+
### `fas publish`
|
|
109
|
+
|
|
110
|
+
Provision and publish an app to FreeAppStore (or FreeGameStore). Runs compliance checks, authenticates, creates a GitHub repo + R2 hosting route + storefront registry entry via the admin Worker, and injects a deploy workflow.
|
|
43
111
|
|
|
44
112
|
By default, `publish` is interactive — it asks for category, type, oneliner, and demo URL. Skip prompts by passing flag values; combine with `--yes` to fail fast in CI rather than hang on a missing field.
|
|
45
113
|
|
|
114
|
+
```bash
|
|
115
|
+
fas publish # interactive
|
|
116
|
+
fas publish --store games # publish to FreeGameStore instead
|
|
117
|
+
fas publish \
|
|
118
|
+
--name my-app \
|
|
119
|
+
--category Utilities \
|
|
120
|
+
--type standalone \
|
|
121
|
+
--oneliner "Does the thing." \
|
|
122
|
+
--yes # non-interactive (CI)
|
|
123
|
+
```
|
|
124
|
+
|
|
46
125
|
| Flag | Purpose |
|
|
47
126
|
|---|---|
|
|
48
127
|
| `--name <id>` | App id (lowercase, used as subdomain). Defaults to `package.json#name`. |
|
|
@@ -54,17 +133,136 @@ By default, `publish` is interactive — it asks for category, type, oneliner, a
|
|
|
54
133
|
| `--issue` | Skip auto-provision; open the GitHub Issue submission form instead. |
|
|
55
134
|
| `--skip-checks` | Skip `fas check` before publish (not recommended). |
|
|
56
135
|
|
|
57
|
-
|
|
136
|
+
### `fas list` (alias `fas ls`)
|
|
137
|
+
|
|
138
|
+
List apps and games you have published. Shows app id, category, live URL, and creation date.
|
|
58
139
|
|
|
59
140
|
```bash
|
|
60
|
-
fas
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
141
|
+
fas list # human-readable table
|
|
142
|
+
fas list --json # full JSON with per-app commit history
|
|
143
|
+
fas list -v # verbose — show last 3 commits per app
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
| Flag | Purpose |
|
|
147
|
+
|---|---|
|
|
148
|
+
| `--json` | Output JSON instead of a table (includes per-app commit history). |
|
|
149
|
+
| `-v, --verbose` | Show recent commits per app (fetches last 3 from each app repo via GitHub API). |
|
|
150
|
+
|
|
151
|
+
### `fas logs <app-id>`
|
|
152
|
+
|
|
153
|
+
Tail live deployment logs for an app's Cloudflare Pages project. Requires `wrangler` to be installed globally.
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
fas logs calculator
|
|
157
|
+
fas logs calculator --cf-project freecalculator
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
| Flag | Purpose |
|
|
161
|
+
|---|---|
|
|
162
|
+
| `--cf-project <name>` | Override the Cloudflare Pages project name (auto-derived by default). |
|
|
163
|
+
|
|
164
|
+
### `fas secret set|list|rm`
|
|
165
|
+
|
|
166
|
+
Manage server-side encrypted API keys for an app. Secrets are stored on the platform and injected at runtime via the proxy. Values are encrypted at rest; `list` only shows names, never values.
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
fas secret set OPENWEATHER_KEY sk-abc123 # store a secret
|
|
170
|
+
fas secret set OPENWEATHER_KEY sk-abc123 --app my-app # explicit app id
|
|
171
|
+
fas secret list # list secret names
|
|
172
|
+
fas secret list --json # machine-readable
|
|
173
|
+
fas secret rm OPENWEATHER_KEY # delete a secret
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
| Subcommand | Usage | Description |
|
|
177
|
+
|---|---|---|
|
|
178
|
+
| `set` | `fas secret set <name> <value> [--app <id>]` | Store or replace an encrypted API key. Name must be uppercase + underscores. |
|
|
179
|
+
| `list` (alias `ls`) | `fas secret list [--app <id>] [--json]` | List secret names registered for an app. |
|
|
180
|
+
| `rm` (alias `remove`) | `fas secret rm <name> [--app <id>]` | Delete a stored secret. |
|
|
181
|
+
|
|
182
|
+
All subcommands accept `--app <id>` to specify the app explicitly. If omitted, the app id is derived from the `name` field in the current directory's `package.json`.
|
|
183
|
+
|
|
184
|
+
### `fas proxy allow|list|deny`
|
|
185
|
+
|
|
186
|
+
Manage the URL allowlist for the per-app secret-injecting proxy. The proxy intercepts outbound API calls from your app and injects the appropriate secret (as a query param, header, bearer token, or OAuth2 client credentials exchange) so that API keys never reach the browser.
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
# Allow the proxy to inject OPENWEATHER_KEY as a query param when calling the API
|
|
190
|
+
fas proxy allow "https://api.openweathermap.org/" \
|
|
191
|
+
--secret OPENWEATHER_KEY \
|
|
192
|
+
--inject "query:appid"
|
|
193
|
+
|
|
194
|
+
# Inject as a Bearer token
|
|
195
|
+
fas proxy allow "https://api.example.com/v1/" \
|
|
196
|
+
--secret EXAMPLE_TOKEN \
|
|
197
|
+
--inject bearer
|
|
198
|
+
|
|
199
|
+
# OAuth2 client credentials flow
|
|
200
|
+
fas proxy allow "https://api.spotify.com/v1/" \
|
|
201
|
+
--secret SPOTIFY_CLIENT_ID \
|
|
202
|
+
--secret2 SPOTIFY_CLIENT_SECRET \
|
|
203
|
+
--inject oauth2_cc \
|
|
204
|
+
--token-url "https://accounts.spotify.com/api/token"
|
|
205
|
+
|
|
206
|
+
# List current rules
|
|
207
|
+
fas proxy list
|
|
208
|
+
fas proxy list --json
|
|
209
|
+
|
|
210
|
+
# Remove a rule
|
|
211
|
+
fas proxy deny "https://api.openweathermap.org/"
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
| Subcommand | Usage | Description |
|
|
215
|
+
|---|---|---|
|
|
216
|
+
| `allow` | `fas proxy allow <pattern> --secret <name> --inject <spec> [flags]` | Add an allowlist rule. `<pattern>` is a URL prefix (must start with `https://`). |
|
|
217
|
+
| `list` (alias `ls`) | `fas proxy list [--app <id>] [--json]` | Show all proxy allowlist rules for the app. |
|
|
218
|
+
| `deny` (alias `rm`) | `fas proxy deny <pattern> [--app <id>]` | Remove an allowlist rule by its exact pattern. |
|
|
219
|
+
|
|
220
|
+
**`allow` flags:**
|
|
221
|
+
|
|
222
|
+
| Flag | Purpose |
|
|
223
|
+
|---|---|
|
|
224
|
+
| `--secret <name>` | **(required)** Name of a previously stored secret (see `fas secret set`). |
|
|
225
|
+
| `--inject <spec>` | **(required)** How to inject: `query:<name>`, `header:<name>`, `bearer`, or `oauth2_cc`. |
|
|
226
|
+
| `--secret2 <name>` | Second secret (the `client_secret` for `oauth2_cc`). |
|
|
227
|
+
| `--token-url <url>` | OAuth2 token endpoint (required for `oauth2_cc`). |
|
|
228
|
+
| `--methods <list>` | Comma-separated HTTP methods. Default: `GET`. |
|
|
229
|
+
| `--app <id>` | App id (defaults to `package.json` name in cwd). |
|
|
230
|
+
|
|
231
|
+
### `fas screencheck`
|
|
232
|
+
|
|
233
|
+
Build the app and run a headless Chromium browser at every reference viewport in the device matrix (portrait + landscape, from iPhone SE to iPad Pro). Reports whether the layout fits without scrolling or clipping, and computes device coverage percentages. Requires Playwright as a dev dependency in the app project.
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
fas screencheck # build + test local dist
|
|
237
|
+
fas screencheck --skip-build # test existing dist without rebuilding
|
|
238
|
+
fas screencheck --screenshots # save a PNG per viewport to ./screencheck-out/
|
|
239
|
+
fas screencheck --url https://my-app.freeappstore.online # test a live deployment
|
|
66
240
|
```
|
|
67
241
|
|
|
242
|
+
| Flag | Purpose |
|
|
243
|
+
|---|---|
|
|
244
|
+
| `--dir <path>` | Repo directory to check. Defaults to cwd. |
|
|
245
|
+
| `--port <n>` | Port for the local static server. Default: `4571`. |
|
|
246
|
+
| `--skip-build` | Skip `pnpm build` -- assume `web/dist` is already current. |
|
|
247
|
+
| `--screenshots` | Save a PNG of every viewport to `./screencheck-out/`. |
|
|
248
|
+
| `--url <url>` | Check a live URL instead of building and serving locally. |
|
|
249
|
+
|
|
250
|
+
### `fas quality [app-id]`
|
|
251
|
+
|
|
252
|
+
Show the VCQA (VibeCode QA) code quality report for an app. Fetches the latest report from the platform API and displays the composite score (0--100), letter grade (A--F), per-check breakdown, and top issues.
|
|
253
|
+
|
|
254
|
+
If `app-id` is omitted, the command auto-detects it from the current directory's `package.json` name, a `*.freeappstore.online` reference in `CLAUDE.md`, or the directory basename.
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
fas quality # auto-detect app id from cwd
|
|
258
|
+
fas quality timer # explicit app id
|
|
259
|
+
fas quality timer --json # raw JSON for scripting
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
| Flag | Purpose |
|
|
263
|
+
|---|---|
|
|
264
|
+
| `--json` | Output the raw JSON report instead of the formatted summary. |
|
|
265
|
+
|
|
68
266
|
## Configuration
|
|
69
267
|
|
|
70
268
|
| Env var | Purpose |
|