@velven/cli 0.0.1 → 0.2.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/CHANGELOG.md +22 -0
- package/README.md +129 -2
- package/dist/velven.js +1644 -0
- package/package.json +33 -7
- package/bin/velven.js +0 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
- `velven publish --prod` is usually live when the command ends: Velven reads every file of the version, and a clean
|
|
6
|
+
version goes live in the same request. The CLI prints the page at once, with no waiting. Sometimes a
|
|
7
|
+
version answers `publishing` instead and waits on Velven, usually for less than a minute; `--wait` waits for it as
|
|
8
|
+
before. An older server's `checking` is treated the same way.
|
|
9
|
+
- A version Velven refuses in the publish itself (a program, an installer or a coin miner) prints the reason naming
|
|
10
|
+
the file and says to remove it and publish again, since no review changes that (`--json`: `code: "scan_refused"`),
|
|
11
|
+
and exits 6 with or without `--wait`.
|
|
12
|
+
- A program, an installer or a coin miner in the folder is refused before anything is uploaded, naming the file: exit
|
|
13
|
+
4, code `refused_file`.
|
|
14
|
+
- `velven.json` takes `thumbnail` (a JPEG, PNG or WebP up to 2 MB) and `clip` (an MP4 or WebM up to 3 MB) for the
|
|
15
|
+
space's tile. Each is checked before anything is uploaded: exit 2, code `invalid_media`.
|
|
16
|
+
- The printed lines, the help and the README say "publishing" and "waiting on Velven to publish it" for a version that
|
|
17
|
+
waits.
|
|
18
|
+
|
|
19
|
+
## 0.1.0
|
|
20
|
+
|
|
21
|
+
- The first release: `login`, `logout`, `whoami`, `publish` (previews, `--prod`, `--wait`, `--json`, publishing
|
|
22
|
+
without an account), `versions`, `rollback`, `dev` and `reset`.
|
package/README.md
CHANGED
|
@@ -1,5 +1,132 @@
|
|
|
1
1
|
# @velven/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Publish a folder to [Velven](https://velven.ai), the community marketplace for spaces built with AI. Velven hosts the files
|
|
4
|
+
and gives you a private preview link; `--prod` puts the version live on its own Velven page with the SDK added, usually
|
|
5
|
+
within seconds.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
```sh
|
|
8
|
+
npx @velven/cli login
|
|
9
|
+
npx @velven/cli publish ./dist # a private preview, link printed
|
|
10
|
+
npx @velven/cli publish ./dist --prod # live on its Velven page
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Or install it: `npm install -g @velven/cli`, then run `velven`. Node 20 or later. No dependencies.
|
|
14
|
+
|
|
15
|
+
## velven.json
|
|
16
|
+
|
|
17
|
+
The listing comes from `velven.json` in the folder you publish. It stays on your machine; it is never uploaded, and neither is a `velven.json` in any folder below, whatever its case.
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"title": "Star Hop",
|
|
22
|
+
"type": "game",
|
|
23
|
+
"devices": ["desktop", "mobile"],
|
|
24
|
+
"description": "Hop between stars before the light runs out.",
|
|
25
|
+
"engine": "three.js"
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Required: `title`, `type` (`game`, `world`, `tool` or `wonder`) and `devices` (`desktop`, `mobile`, `vr`). When one is
|
|
30
|
+
missing, `velven publish` asks for it in a terminal and saves your answer into `velven.json`; anywhere else it stops
|
|
31
|
+
and names each missing field.
|
|
32
|
+
|
|
33
|
+
Optional: `description`, `engine`, `ai_tools`, `models`, `how_made`, `source_url`, and for hosting:
|
|
34
|
+
|
|
35
|
+
| Key | What it does |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| `entry` | The page to open, when it is not `index.html` |
|
|
38
|
+
| `spa` | `true` serves the entry page for any path without a file (client-side routing) |
|
|
39
|
+
| `sdk` | `false` stops Velven adding the SDK's script tag (set it when you bundle `@velven/sdk` yourself) |
|
|
40
|
+
| `start` | How to get past a start screen, so Velven can look at the space and record its clip: `{ "click": "Play" }`, `{ "click": [x, y] }` or `{ "key": "Space" }` |
|
|
41
|
+
| `thumbnail` | A picture in the folder for the space's tile: JPEG, PNG or WebP, up to 2 MB |
|
|
42
|
+
| `clip` | A video in the folder the tile plays on hover: MP4 or WebM, up to 3 MB (five seconds at 480p); without a `thumbnail` its first frame is the picture |
|
|
43
|
+
| `boards`, `achievements`, `stats`, `toasts` | Leaderboards, achievements and stats, declared as in the SDK docs |
|
|
44
|
+
| `space` | Written by the first publish; later publishes update that space |
|
|
45
|
+
| `claim` | Written by a publish without an account; it updates the unlisted page until you claim it |
|
|
46
|
+
|
|
47
|
+
`thumbnail` and `clip` must be files the publish sends (not left out by `.velvenignore`), of their kind by name and by
|
|
48
|
+
their first bytes, and within their size: `velven publish` checks them before uploading anything and stops with exit 2
|
|
49
|
+
(`invalid_media`) naming what is wrong. Velven then records nothing for the tile; a later version that names neither, or
|
|
50
|
+
the same files, keeps what the space shows, a clip recorded again or uploaded on the Clip tab included.
|
|
51
|
+
|
|
52
|
+
A `.velvenignore` file leaves files out: one pattern a line, `*`, `**` and `?`, `folder/` for folders, `#` comments.
|
|
53
|
+
Dotfiles, `node_modules` and every `velven.json` are always left out, in any case, as is a name that ends in a dot or a space or holds `:` or `~` (the CLI names each such file);
|
|
54
|
+
`velven dev` serves by the same rule, `.velvenignore` included, and a path only in the letter case the folder spells it, as the live version
|
|
55
|
+
looks paths up (`Assets/Hero.png` does not open `assets/hero.png`). A link to a file or folder inside the folder is followed (a folder link's files go up under the
|
|
56
|
+
link's name); a link outside the folder, to one of those, or back up to a folder it sits in is left out, and the CLI names each
|
|
57
|
+
link it leaves out. A version holds at most 100 MB and 2,000 files.
|
|
58
|
+
|
|
59
|
+
Velven never serves a program, an installer or a coin miner. Before uploading anything, `velven publish` looks at the
|
|
60
|
+
first bytes of every file (a Windows, Linux or Mac program is refused whatever its name), at every name (`.exe`, `.scr`,
|
|
61
|
+
`.msi`, `.dmg`, `.pkg`, `.app`, `.apk`, `.deb`, `.rpm`, `.jar`, `.bat`, `.cmd`, `.ps1`, `.vbs`; a compressed
|
|
62
|
+
`setup.exe.gz` or `setup.exe.br` by the name inside) and at the text of scripts, pages and WebAssembly for a coin
|
|
63
|
+
miner (a compressed file's text is left to Velven, which reads it inflated), and stops naming the file, with exit 4:
|
|
64
|
+
`dist/setup.exe is a Windows program; Velven does not serve programs. Remove it or add it to .velvenignore.`
|
|
65
|
+
The upload on velven.ai checks the same way. Velven reads the whole version again once it is uploaded, and refuses it
|
|
66
|
+
with exit 6 when it holds one of these.
|
|
67
|
+
|
|
68
|
+
## Commands
|
|
69
|
+
|
|
70
|
+
| Command | What it does |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `velven login` | Sign in: shows a code and opens velven.ai to approve it |
|
|
73
|
+
| `velven logout` | Forget this computer's sign-in |
|
|
74
|
+
| `velven whoami` | Who you are signed in as |
|
|
75
|
+
| `velven publish [dir]` | Upload the folder (only files Velven does not already have) as a private preview; with `--prod`, live on its Velven page |
|
|
76
|
+
| `velven versions` | The space's versions; `*` marks the live one |
|
|
77
|
+
| `velven rollback [version]` | Put an earlier version live again (asks which when you leave it out) |
|
|
78
|
+
| `velven dev [dir]` | Serve the folder on `localhost` and play it on Velven, with scores and saves going to the sandbox |
|
|
79
|
+
| `velven reset` | Delete the space's sandbox data: `--scores --saves --achievements --content --rooms` (default all), `--player <handle>` |
|
|
80
|
+
|
|
81
|
+
`velven publish` options:
|
|
82
|
+
|
|
83
|
+
- Without `--prod`: a private preview. The link works for 24 hours; scores and saves made there go to the sandbox.
|
|
84
|
+
- `--prod`: publish it live on the space's Velven page. Most versions are live when the command ends; a refused one
|
|
85
|
+
prints the reason, naming the file, and exits 6. Sometimes a version waits on
|
|
86
|
+
Velven to publish it, usually for less than a minute, and the CLI prints a link to follow it.
|
|
87
|
+
- `--wait`: wait here for the preview link, or with `--prod` until a version that waits is live. A refused version
|
|
88
|
+
prints the reason; a version Velven could not judge prints what it saw, and a start hint usually fixes it. Either way
|
|
89
|
+
you can ask for a review from the link printed, except for a program or a miner, which is never served: remove the
|
|
90
|
+
file and publish again.
|
|
91
|
+
- `--title`, `--type`, `--devices desktop,mobile`, `--description`, `--engine`: override `velven.json` for this run only.
|
|
92
|
+
- `--yes`: never ask for missing fields; fail naming them instead.
|
|
93
|
+
- `--json`: print one JSON object, for scripts and agents (also on `whoami` and `versions`).
|
|
94
|
+
|
|
95
|
+
`versions`, `rollback` and `reset` act on the space `velven.json` in the current folder names; `--space <slug>` picks another.
|
|
96
|
+
|
|
97
|
+
## Without an account
|
|
98
|
+
|
|
99
|
+
`velven publish` works before you sign in. It makes an **unlisted page** on Velven: live as soon as Velven publishes it,
|
|
100
|
+
with every SDK feature, but not listed anywhere on Velven until you claim it. The CLI prints the page's address, a claim
|
|
101
|
+
token and a claim link, and saves the token in `velven.json` as `"claim"`, so publishing again from the folder updates
|
|
102
|
+
the same page. When `velven.json` cannot be written (read-only, or a folder you cannot write to), the CLI says so, prints
|
|
103
|
+
what to put in it (the token, or signed in the slug as `"space"`) and goes on with the publish; `--json` carries that
|
|
104
|
+
sentence as `notSaved`. An unclaimed page is deleted 7 days after its first publish.
|
|
105
|
+
|
|
106
|
+
To claim it, open the claim link, or run `velven login` and publish again from the folder: the page becomes yours, goes
|
|
107
|
+
on Velven, and `"claim"` in `velven.json` is replaced by `"space"`. Claimed it in the browser? Run `velven login`
|
|
108
|
+
before publishing again: signed out, the claimed page's token exits 3 (`claim_spent`); claimed while the CLI uploads,
|
|
109
|
+
the version was never finished, so it exits 3 saying to run `velven login` and publish again; claimed while it waits
|
|
110
|
+
with `--wait`, it exits 3 with the space's Files tab link, where the version goes on. Without an account a version
|
|
111
|
+
holds at most 50 MB and 1,000 files, and `--prod` needs you to sign in. By publishing you agree to Velven's Terms: https://velven.ai/terms
|
|
112
|
+
|
|
113
|
+
## In CI
|
|
114
|
+
|
|
115
|
+
Set `VELVEN_TOKEN` to a token from `velven login` (in `~/.config/velven/auth.json`) and run
|
|
116
|
+
`velven publish --prod --yes --wait`. The token takes precedence over a saved sign-in. Revoke tokens in your Velven settings.
|
|
117
|
+
|
|
118
|
+
`VELVEN_API` points the CLI at another Velven, such as `http://localhost:3000` when running Velven itself locally.
|
|
119
|
+
|
|
120
|
+
## Exit codes
|
|
121
|
+
|
|
122
|
+
| Code | Meaning |
|
|
123
|
+
| --- | --- |
|
|
124
|
+
| 0 | Done |
|
|
125
|
+
| 1 | Failed: the network, a server error, a failed upload, or cancelled |
|
|
126
|
+
| 2 | A mistake in the command or in `velven.json`, such as a missing field, or a `thumbnail` or `clip` that is not right (`invalid_media`) |
|
|
127
|
+
| 3 | Not signed in (or the token was refused) for something that needs an account, such as `--prod` |
|
|
128
|
+
| 4 | Refused by Velven: not your space, too large, too many files, a program, installer or coin miner in the folder (`refused_file`, before anything is uploaded), not found |
|
|
129
|
+
| 5 | Rate limited: try again later |
|
|
130
|
+
| 6 | Not published: Velven refused the version, or with `--wait`, could not judge it |
|
|
131
|
+
|
|
132
|
+
Docs: https://velven.ai/docs
|