turnzero 0.12.0 → 0.12.1-next.1
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 +19 -429
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,441 +1,31 @@
|
|
|
1
1
|
# turnzero
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Turn Zero Cloud connects to your AI coding tool through a Model Context Protocol (MCP) server. Once connected, your AI can code, build, and test backends, connect them to your app, and host your code in the cloud.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Turn Zero Cloud is for developers who build with an AI coding tool and do not want to run servers. Your tool writes, builds, and tests the application on your computer. The platform builds it, runs it in production at the application's address, and records its logs, counters, and usage. To start, connect your AI tool: https://turnzero.ai/cloud/getting-started/connect-your-tool/
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## What this package is
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The turnzero command-line tool is used by the Turn Zero Cloud MCP server. Your AI tool runs it on your computer for the work the platform cannot do from the cloud: reading your files, writing files, and starting your application.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
| --- | --- | --- |
|
|
13
|
-
| `hash` | Prints the SHA-256 hash of the zip a deploy from the folder would upload. No deploy needs it. | No credential. |
|
|
14
|
-
| `deploy` | Zips the application, prepares its upload, uploads it, starts the deploy, and waits for it. | This computer's token, or, in an unattended run, a minted token. |
|
|
15
|
-
| `check` | Checks a deploy before you make it: asks the platform which of a deploy's checks of the application would refuse it now, and runs the deploy's own checks of the zip on your machine. It uploads nothing. | This computer's token, or, in an unattended run, a minted token. |
|
|
16
|
-
| `secret store`, `secret rotate` | Stores a secret under a name, or replaces the value a name holds. | A secret grant, or, with none piped, this computer's token. |
|
|
17
|
-
| `put` | Uploads one file to a storage area of an application. | An upload grant. |
|
|
18
|
-
| `export download` | Downloads every file of a completed export. | A download grant. |
|
|
19
|
-
| `library take` | Takes a library entry into your project. | No credential. |
|
|
20
|
-
| `provision` | Re-mints an application's development credentials and writes the environment file. | A secret grant, or, in an unattended run, a minted token. |
|
|
21
|
-
| `run` | Starts your application on your machine with the environment file's settings. | No credential. |
|
|
22
|
-
| `scaffold` | Writes a new service from a template into your project: `hello-world` where the line names none, `database-service`, or `scheduled-job`. It takes the template's library package where it has one, installs, and runs the service's tests. | No credential. |
|
|
23
|
-
| `authorize` | Authorizes this computer at the platform's address. With nothing piped, it prints a challenge and the `mint_token` call to make. With the token code that call's line pipes in, it keeps this computer's token. | A token code. |
|
|
24
|
-
| `logout` | Ends this computer's authorization at the platform's address: it revokes this computer's token and removes it from the computer. | This computer's token. |
|
|
25
|
-
| `token request`, `token claim` | Prints a challenge and the `mint_token` call for a token that is not this computer's, or, run by you in your own terminal, prints that token's value once. | Under `token claim`, a token code. |
|
|
11
|
+
You do not install it. The MCP server gives your AI tool each command line to run, and `npx` fetches this package from npm when that line runs. It needs Node.js 24 or later.
|
|
26
12
|
|
|
27
|
-
|
|
13
|
+
## Subcommands
|
|
28
14
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
<command> logout [--origin <origin>]
|
|
42
|
-
[echo <token code> |] <command> token request|claim [--origin <origin>]
|
|
43
|
-
```
|
|
15
|
+
- `deploy` zips your application, uploads it, deploys it, and waits for the result.
|
|
16
|
+
- `check` tells you whether a deploy would be refused, without uploading anything.
|
|
17
|
+
- `hash` prints the hash of the zip a deploy would upload.
|
|
18
|
+
- `secret store` and `secret rotate` store a secret under a name, or replace its value.
|
|
19
|
+
- `put` uploads one file to a storage area.
|
|
20
|
+
- `export download` downloads every file of a finished export.
|
|
21
|
+
- `library take` copies a library entry into your project.
|
|
22
|
+
- `provision` gets new development credentials for your application and writes them to its environment file.
|
|
23
|
+
- `run` starts your application on your computer with that file's settings.
|
|
24
|
+
- `scaffold` writes a new service into your project from a template, installs it, and runs its tests.
|
|
25
|
+
- `authorize` gives this computer a token to act on your account, and `logout` revokes it.
|
|
26
|
+
- `token request` and `token claim` get a token for another computer or for an unattended run.
|
|
44
27
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
Each line has two forms, one for macOS and Linux and one for Windows, which differ in one word, and each runs the same in every shell of its operating system. On Windows, write `npx.cmd` for `npx`, because Windows PowerShell refuses `npx` where running scripts is disabled. No tool call returns the `hash` line, which reads what a deploy from the folder would upload and sends nothing. No deploy needs it first. Its macOS and Linux form:
|
|
48
|
-
|
|
49
|
-
```text
|
|
50
|
-
npx -y turnzero@latest hash
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
A deploy is one line, run from the application's folder, and the line carries no credential. Your tool calls `deploy` with the application, naming no environment and neither an artifact nor an upload. The response's `command` is the line, and `command_windows` is its Windows form. Your tool runs the one for its operating system, as given. The macOS and Linux form:
|
|
54
|
-
|
|
55
|
-
```text
|
|
56
|
-
npx -y turnzero@latest deploy --application <application id>
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
The line also names `--path` where the call named `local_path`, `--origin` where the platform is at another address, and `--rotate-database-credential` where the call named `rotate_database_credential`.
|
|
60
|
-
|
|
61
|
-
`deploy` reads nothing on its standard input. It reads its credential in this order:
|
|
62
|
-
|
|
63
|
-
1. The minted token in `TURNZERO_CLOUD_MINTED_TOKEN`, where that variable is set, as Unattended runs describes.
|
|
64
|
-
2. Otherwise, this computer's token for the platform's address, from the credential file `authorize` writes. The address is the line's `--origin`, else the one in `TURNZERO_CLOUD_ORIGIN`, else `https://turnzero.ai`, and the token goes there alone.
|
|
65
|
-
3. Otherwise, where the file holds no token for the address, or one that has expired, the command sends nothing. It says so, prints two routes to a credential, and ends with status 3.
|
|
66
|
-
|
|
67
|
-
In that third case, the printed lines give two routes, the variable route first. They print it even where the address is one `authorize` does not reach or the credential file cannot be written. A tool connected by a minted token, or a job, cannot use `mint_token`, which takes a sign-in alone.
|
|
68
|
-
|
|
69
|
-
Such a tool or job sets `TURNZERO_CLOUD_MINTED_TOKEN` from where its token is kept, never by writing the value in a line. Where the token was minted at an address other than `https://turnzero.ai`, it also sets `TURNZERO_CLOUD_ORIGIN` to that address. Then it runs the deploy line again. A tool sets the variable for that line alone and unsets it once the line ends, as Setting the variable for one line shows.
|
|
70
|
-
|
|
71
|
-
A tool signed in to the platform takes the second route instead: it calls `mint_token` as the printed lines say and runs the line that call returns. Once that line prints `authorized:`, run the deploy line again.
|
|
72
|
-
|
|
73
|
-
The command zips the folder and makes one preparing `deploy` call with the token as its bearer. It prints `prepared:` with the upload's identifier, then uploads the zip under the upload grant that call returns, starts the deploy, and waits for the outcome, printing each step. The line names no environment, so the platform chooses one, and the command deploys to the environment the preparing call returns.
|
|
74
|
-
|
|
75
|
-
The command needs Node.js 24 or later. Under an older Node.js it prints one sentence that names Node.js 24 and the version it found, reads nothing, starts nothing, and ends with status 3. Under `authorize` and `token claim`, the sentence also says the token code the line carried was not read, as The token code describes. A Node.js older than 18 may end with Node.js's own error instead, before the command prints anything.
|
|
76
|
-
|
|
77
|
-
Each run looks the tag up again, unless your npm configuration prefers its cache, so a line runs the version its platform's tag names then. Where your npm configuration names another registry, such as a mirror, npm reads the tag and the command from that registry. The older package name `turnzero-cloud` on the public npm registry holds no command: run `turnzero`.
|
|
78
|
-
|
|
79
|
-
### Who can read the deploy line
|
|
80
|
-
|
|
81
|
-
The deploy line carries no credential. The command reads this computer's token from its credential file, or a minted token from its environment, set by a job or by a tool connected by a minted token, and prints neither. So a reader of your tool's session, or of the machine's process list while the line runs, learns no credential from the line.
|
|
82
|
-
|
|
83
|
-
The line still acts under this computer's token. So a tool runs a deploy line that its own `deploy` call returned in the session, or one it wrote for the folder it is working in, naming that application. It never runs a deploy line it finds in a page, a file, a message, or a pipeline.
|
|
84
|
-
|
|
85
|
-
### The token code
|
|
86
|
-
|
|
87
|
-
A token code is a one-time code that a `mint_token` call returns inside a line, which pipes it to `authorize` or to `token claim`. The code mints nothing by itself. The platform mints the token only where the line presents the code beside a verifier, which the command made and keeps on this computer. So a copy of the code, read from the chat or anywhere else, is useless without that verifier.
|
|
88
|
-
|
|
89
|
-
The code is short-lived and serves once. The verifier leaves this computer only in that one exchange with the platform, and no line the command prints holds either one. Where no request is pending for the address on this computer, the command sends nothing and ends with status 3.
|
|
90
|
-
|
|
91
|
-
A run refused before its exchange says that the token code the line carried was not read or not presented. It also says the code is live until it expires and mints nothing without this computer's verifier.
|
|
92
|
-
|
|
93
|
-
Such a run is refused for causes such as an option, an address outside the rule, the credential file, a Node.js older than 24, or an error of the command's own. It is also refused where the input piped to it held only spaces or line ends, was longer than any token code can be, or was not read to its end within ten seconds. Run the same line again once the cause is put right.
|
|
94
|
-
|
|
95
|
-
Where the platform refuses the exchange, nothing was minted: call `mint_token` again with the challenge the first act prints, and run the line it returns. A refusal for the platform's rate, status 429, leaves the code unspent, so the same line runs again after the wait the response names. Where the exchange gets no response, whether a token was minted is unknown. `list_tokens` shows each token by its label, and `revoke_token` ends one that nothing holds.
|
|
96
|
-
|
|
97
|
-
## Unattended runs
|
|
98
|
-
|
|
99
|
-
A job that has no AI tool to call `deploy` for it, such as a CI job, runs `deploy`, `check`, or `provision` under a minted token. An AI tool connected by a minted token rather than a sign-in runs `deploy` and `check` alone under one. The token comes from `TURNZERO_CLOUD_MINTED_TOKEN`, which the job sets from its secret store and the tool from where its token is kept, never by writing the value in a line. The tool sets it for the deploy or check line alone, as Setting the variable for one line shows.
|
|
100
|
-
|
|
101
|
-
A job's token should be minted for the application, with an expiry. Where the platform is not at `https://turnzero.ai`, the job or the tool also sets `TURNZERO_CLOUD_ORIGIN` to its address. Where the variable is set, it wins over this computer's credential file, and the command never reads a token from its arguments.
|
|
102
|
-
|
|
103
|
-
An unattended `deploy` is the deploy line itself, and it may name `--env` to choose the environment, which the platform otherwise chooses. The command reads nothing on its standard input, so the job need not close it. Where the platform refuses the preparing call under the variable's token, the command says the variable was the credential it read. It also says whether this computer's credential file holds a token for the address.
|
|
104
|
-
|
|
105
|
-
The job's token is minted so that its value never passes through your AI tool:
|
|
106
|
-
|
|
107
|
-
1. `token request` keeps a verifier on this computer and prints a challenge and the `mint_token` call to make. Your tool may run it, since it prints nothing secret.
|
|
108
|
-
2. Your tool calls `mint_token` with that challenge, beside the token's scope, application, grants, label, and expiry. The response has a `token claim` line.
|
|
109
|
-
3. You run that line yourself, in a terminal outside the AI tool, on the same computer and as the same user. Pipe it into your secret store's command, such as `| gh secret set TURNZERO_CLOUD_MINTED_TOKEN`, and read the line's tag and `--origin` before you run it.
|
|
110
|
-
|
|
111
|
-
The command zips the folder and makes the preparing `deploy` call under the token, then uploads, starts, and waits under the upload grant that call returns. The token goes to that call alone, and to no other request, and that call follows no redirect. `deploy` never reads `TURNZERO_CLOUD_TOKEN`, the application's own credential.
|
|
112
|
-
|
|
113
|
-
The environment the job or the tool sets, not the line, says where the token goes. Where the line names no `--origin`, the command sends the token to the address in `TURNZERO_CLOUD_ORIGIN`, or to `https://turnzero.ai` where that variable is not set. Where the line names `--origin`, it must be `https://turnzero.ai` or the address in `TURNZERO_CLOUD_ORIGIN`, and an address on the machine itself is allowed only where that variable names it.
|
|
114
|
-
|
|
115
|
-
Any other `--origin` ends the run with status 3 before anything is sent, and so does a `TURNZERO_CLOUD_ORIGIN` that is not an `https` address or an address on the machine itself. A run under a grant does not read `TURNZERO_CLOUD_ORIGIN`: the line says where a grant goes.
|
|
116
|
-
|
|
117
|
-
An unattended `provision` makes its two re-mints under the token, as a run under a grant makes them under the grant, and sends the token where the same rule allows.
|
|
118
|
-
|
|
119
|
-
### Setting the variable for one line
|
|
120
|
-
|
|
121
|
-
A tool sets `TURNZERO_CLOUD_MINTED_TOKEN` for the deploy or check line alone and unsets it once the line ends. So no later line in the tool's shell runs under the token. A job's variable is its step's own, so a job needs no such form.
|
|
122
|
-
|
|
123
|
-
The value comes from where the token is kept, such as a variable your tool names or a file read inside the line. The line never writes the value out. Off `https://turnzero.ai`, set `TURNZERO_CLOUD_ORIGIN` the same way, beside the token, for the line alone. Once the line ends, it holds what it held before.
|
|
124
|
-
|
|
125
|
-
In bash and zsh, the assignment stands before the command, on the same line, and lasts for that command alone. Here the token is read from a file:
|
|
126
|
-
|
|
127
|
-
```bash
|
|
128
|
-
TURNZERO_CLOUD_MINTED_TOKEN="$(cat <token file>)" npx -y turnzero@latest deploy --application <application id>
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
In PowerShell, the assignment and the line stand in a `try`, and the variable's removal in its `finally`, so the variable is removed even where the line fails:
|
|
132
|
-
|
|
133
|
-
```powershell
|
|
134
|
-
try { $env:TURNZERO_CLOUD_MINTED_TOKEN = Get-Content -Raw -ErrorAction Stop <token file>; if (-not $env:TURNZERO_CLOUD_MINTED_TOKEN) { throw 'The token file is empty, so the line did not run.' }; npx.cmd -y turnzero@latest deploy --application <application id> } finally { Remove-Item Env:TURNZERO_CLOUD_MINTED_TOKEN -ErrorAction SilentlyContinue }
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
Here are both forms off `https://turnzero.ai`, with the platform at `https://dev.turnzero.ai`. Each sets `TURNZERO_CLOUD_ORIGIN` beside the token for the line alone. The PowerShell form keeps the variable's earlier value and puts it back in its `finally`, which removes the variable where it was not set:
|
|
138
|
-
|
|
139
|
-
```bash
|
|
140
|
-
TURNZERO_CLOUD_MINTED_TOKEN="$(cat <token file>)" TURNZERO_CLOUD_ORIGIN=https://dev.turnzero.ai npx -y turnzero@next deploy --application <application id> --origin https://dev.turnzero.ai
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
```powershell
|
|
144
|
-
$heldOrigin = $env:TURNZERO_CLOUD_ORIGIN; try { $env:TURNZERO_CLOUD_MINTED_TOKEN = Get-Content -Raw -ErrorAction Stop <token file>; $env:TURNZERO_CLOUD_ORIGIN = 'https://dev.turnzero.ai'; if (-not $env:TURNZERO_CLOUD_MINTED_TOKEN) { throw 'The token file is empty, so the line did not run.' }; npx.cmd -y turnzero@next deploy --application <application id> --origin https://dev.turnzero.ai } finally { Remove-Item Env:TURNZERO_CLOUD_MINTED_TOKEN -ErrorAction SilentlyContinue; $env:TURNZERO_CLOUD_ORIGIN = $heldOrigin }
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
A shell with no form here runs the deploy line from PowerShell or bash instead.
|
|
148
|
-
|
|
149
|
-
## What each subcommand does
|
|
150
|
-
|
|
151
|
-
### hash
|
|
152
|
-
|
|
153
|
-
`hash` builds the zip that `deploy` uploads from the same folder, or takes a `.zip` file as it is, and prints its SHA-256 on its first line. It reads no credential and sends nothing.
|
|
154
|
-
|
|
155
|
-
For a folder with nothing more to report, and without `--list`, that is its only line. After it, `hash` prints up to four more lines, each only where it applies: the paths the zip left out, a warning for a `.zip` file at the top of the folder, a warning for a file that looks like a key or a credential, and a warning for a health path in `manifest.json` that no other file in the zip contains, package files and documentation set aside. None of them changes the status or the zip. With `--list`, it then prints one line for each file the zip holds, so it shows what a deploy from the folder would upload.
|
|
156
|
-
|
|
157
|
-
### deploy
|
|
158
|
-
|
|
159
|
-
`deploy` reads its credential in the order How it runs gives: the minted token, else this computer's token for the address. With neither, it sends nothing, prints the two routes to a credential, the minted token's variables first, and ends with status 3.
|
|
160
|
-
|
|
161
|
-
Otherwise it builds the zip, or takes a `.zip` file as it is, and makes the preparing `deploy` call under the token. Where that call's response says the environment runs no version yet and names the manifest's health path, and no file of the folder's zip names that path, it prints the platform's own refusal and ends with status 3, uploading nothing. Otherwise it uploads the zip under the upload grant that call returns. It then starts the deploy, naming the application's Git commit where one can be read, and waits for the outcome, printing each step. It makes the preparing call, the upload, and the start once each, and never again.
|
|
162
|
-
|
|
163
|
-
The platform checks whether the upload's grant allows a start in the environment that `--env` names. Where the line names no `--env`, the start names the environment the preparing call returned. Where the platform refuses the start, the upload is already stored and the command ends with status 3. The way on is the same line again.
|
|
164
|
-
|
|
165
|
-
After its `zip:` line, `deploy` prints the paths the zip left out and the warning for a `.zip` file at the top of the folder, as `hash` does. Then it prints the warning for a file that looks like a key or a credential, and the health path warning.
|
|
166
|
-
|
|
167
|
-
### check
|
|
168
|
-
|
|
169
|
-
`check` tells you what a deploy would refuse, before you make it, and uploads nothing. Run it before a first deploy and after each fix. Your tool calls `check_deploy` with the application, and the response's `command` is the line, `command_windows` its Windows form. The line can also be written by hand: `<command> check --application <application id>`, run from the application's folder.
|
|
170
|
-
|
|
171
|
-
`check` reads its credential as `deploy` does, in the order How it runs gives, and builds the same zip. With no credential, it prints what `deploy` prints, its last sentence naming the check line, and ends with status 3.
|
|
172
|
-
|
|
173
|
-
Otherwise it prints its `zip:` line and makes one `check_deploy` call under the token. That call names the application alone: no byte of the zip and no hash leaves your machine. The call follows no redirect and is never made twice.
|
|
174
|
-
|
|
175
|
-
The platform answers which of a deploy's checks of the application's state would refuse it now. Examples are a deploy already in flight, a missing secret, or the day's deploy limit. It also says whether the deploy would be the environment's first, and the recorded manifest's health path.
|
|
176
|
-
|
|
177
|
-
`check` then runs the deploy's own checks of the zip, the same code the platform runs: whether the zip can be read, its layout, and, on a first deploy, the health path against the source text. Where the platform's answer cannot be used, or the call gets no response, `check` ends with status 3 and checks nothing.
|
|
178
|
-
|
|
179
|
-
A passing check is not a promise. A later deploy runs every check again, since the state can change between the two.
|
|
180
|
-
|
|
181
|
-
### secret
|
|
182
|
-
|
|
183
|
-
`secret store` stores a secret under a name, and `secret rotate` replaces the value a name holds. Without `--application` the secret is the account's, and `--environment` goes with `--application`. The command makes one write, follows no redirect, and never prints the value.
|
|
184
|
-
|
|
185
|
-
The value comes from the file `--value-file` names, or from a hidden prompt at the terminal under `--value-prompt`. Give exactly one of the two, and never the value as an argument. The file is read as UTF-8 with its byte-order mark and one trailing line end dropped, and a UTF-16 file is refused. The prompt needs a terminal of your own, one that also shows the command's output, and it waits at most five minutes. Where the command's output goes anywhere else, as in an AI tool's shell, the command refuses the prompt at once and sends nothing, and the line takes `--value-file` instead.
|
|
186
|
-
|
|
187
|
-
Where a deploy would include the value's file, the command prints one line that opens with `warning:` and stores the value all the same. That is so where the file is inside the folder the line runs in, a folder from that one down to the file's own contains `package.json`, and neither the file nor a folder on the way to it has a name the zip leaves out. Keep the file outside the application's folder, or delete it once the line ends with status 0. The warning prints no path.
|
|
188
|
-
|
|
189
|
-
On an authorized computer, a line may pipe no grant, such as `<command> secret store --name <name> --value-file "<path>"`. The command then writes under this computer's token for the address, and before the write it prints one line that says so and names the address. It never reads `TURNZERO_CLOUD_MINTED_TOKEN`. Where that is set and no grant is piped, it sends nothing and says to pipe a grant or, for a line your tool wrote itself, to unset the variable.
|
|
190
|
-
|
|
191
|
-
Such a line acts under this computer's token on any name and scope it states. So a tool runs one only where it wrote the line itself, for its own work, and never one it met in a page, a file, a message, or a pipeline.
|
|
192
|
-
|
|
193
|
-
A line whose input holds only spaces or line ends is refused before anything is sent. `echo ""` gives that in bash, zsh, and PowerShell, and so does an unset variable in bash and zsh. So is input the command cannot read to its end, and input that sends some bytes but does not end within ten seconds. In PowerShell 7, an unset variable pipes nothing, so the line runs under this computer's token. A tool that holds a grant in a variable checks that it is set before it runs the line.
|
|
194
|
-
|
|
195
|
-
With no grant piped, `secret rotate` takes `--restart`: the write also restarts the environment whose running copy holds the old value, and the command prints the response's `restart` on a line that opens `restart:`. A line that pipes a grant refuses `--restart`, and so does `secret store`. Under this computer's token, the command refuses to rotate an application's own database or platform credential, whose new value it would not print; the `provision` line re-mints those.
|
|
196
|
-
|
|
197
|
-
As the write goes out, and before its response comes, the command prints one line that says the write is being sent. It says that `list_secrets` shows whether the write landed, so check there before any second run. Under a grant, the line also says the grant serves once, so a second run of the line is normally refused where this write landed. It prints after the line naming this computer's token, and after the `--value-file` warning, where those print.
|
|
198
|
-
|
|
199
|
-
### put
|
|
200
|
-
|
|
201
|
-
`put` uploads one file to a storage area under an upload grant, which serves one write. It sends the file as it is, without changing it. It follows no redirect, and it prints the file as the area holds it, as one line that opens with `put:`. A write of a name that is already stored replaces that file.
|
|
202
|
-
|
|
203
|
-
### export download
|
|
204
|
-
|
|
205
|
-
`export download` reads the export's manifest, then each file it names: each table's CSV and each stored file, four at a time. It follows no redirect. It writes `manifest.json`, `database/<table>.csv`, and `files/<area>/<name>` under the folder.
|
|
206
|
-
|
|
207
|
-
Each file is written first as a partial file under `.turnzero-cloud-partial`, and moved into place once its bytes reach the length the platform stated. A file that falls short is a failed file and is removed. A complete file whose version differs from the manifest's is kept and reported on a line that opens with `moved:`. A name is written under an escaped name where the local file system would change it, where it collides with another, or where it holds a character you would not see, such as a control character or a character that reverses the order of the text. A line that opens with `escaped:` says so.
|
|
208
|
-
|
|
209
|
-
Every name the command prints is whole, with each character you would not see replaced by a percent escape, such as a control character, a zero-width character, or a tag character. A name with a `.` or `..` segment, between slashes or backslashes, is a failed file, and nothing is read for it.
|
|
210
|
-
|
|
211
|
-
The folder is the one `--path` names, or `export-<export id>` where none is named. It must be new, empty, or one an earlier run of the same export wrote, which holds `.turnzero-cloud-export.json`. Where the line names no `--path` and the folder it runs in holds `package.json`, the command refuses before any request and writes nothing, because a deploy from that application's folder would include the export. Run the line again with `--path` naming a folder outside it, under the same grant. The command also refuses, with nothing written, a folder that holds a link leading outside it.
|
|
212
|
-
|
|
213
|
-
A second run into the folder skips the files already on disk and reads the failed ones again. Where the platform answered a file the manifest names as an absent name, with HTTP 404 `no_such_file`, the file was not read, and the closing lines name a fresh export, which has the application's files as they now stand. A read answered HTTP 502, 503, or 504 is made again after 2, then 4, then 8 seconds, at most three more times, and each try prints one line. Where the platform caps the reads for a minute, the command prints a line that opens with `waiting:` and reads again in the next minute. Where the grant ends before the last file, the command stops, prints the counts, and ends with status 2.
|
|
214
|
-
|
|
215
|
-
### library take
|
|
216
|
-
|
|
217
|
-
`library take` reads one entry's file list and each file from the library, which needs no credential. A read answered HTTP 502, 503, or 504 is made again after 2, then 4, then 8 seconds, at most three more times. It checks each file's SHA-256 and the entry's closure hash before it writes anything. It then writes the entry's row in the library folder's `manifest.json` and replaces the entry's folder under the library folder whole. The library folder is the project's own `system/`, else the folder a `system.json` file names, else a new `system/`.
|
|
218
|
-
|
|
219
|
-
Run it at the project's root. That is the folder that holds `system/` or `system.json` beside `app/`, or, on a first take, the folder where the new `system/` is made. Where the folder holds neither and the folder above it holds one, the command refuses and writes nothing, because the folder may be an application's folder inside that project. The printed sentence gives both ways on: run the line in the folder above, or, where the folder is a project of its own, make an empty `system/` folder in it and run the line again.
|
|
220
|
-
|
|
221
|
-
For an entry with compiled modules, it also copies the entry's `package.json` and `lib/` into the application's folder and runs `npm install` there. The application's folder is `app/` where that holds a `package.json`, else the project root. `npm install` receives neither `TURNZERO_CLOUD_MINTED_TOKEN` nor `TURNZERO_CLOUD_UPLOAD_GRANT`. The command starts npm as `run` does, so an interrupt reaches npm, and the command prints its own lines after it. On Windows, its last line then says that cmd may ask `Terminate batch job (Y/N)?`.
|
|
222
|
-
|
|
223
|
-
A first take writes the copy beside the application's code and declares it as `@turnzero/<name>`. Where the package file is `app/package.json`, the copy is `app/lib/<name>`, declared `file:lib/<name>`. Where the package file is at the project root and the project has an `app/` folder, the copy is `app/lib/<name>`, declared `file:app/lib/<name>`. Where the package file is at the project root and there is no `app/` folder, the copy is `lib/<name>`, declared `file:lib/<name>`. Where the package file already declares the entry at a `file:` path, the take replaces the copy at that path and keeps the declaration.
|
|
224
|
-
|
|
225
|
-
A refusal writes nothing. The command refuses a library folder, an entry's folder, or a copy that is reached through a link leading outside the project. It also refuses where a link stands at a name it writes, wherever the link leads. Those names are the library folder's `manifest.json`, the `manifest.json.partial` beside it and beside the application manifest, and the `package.json` it adds the declaration to. They also include the `.take` staging names in the library folder and beside the copy.
|
|
226
|
-
|
|
227
|
-
The command prints the name and version of each row of the library folder's manifest, for the application manifest's `packages` member, on a line that opens with `packages:`.
|
|
228
|
-
|
|
229
|
-
### provision
|
|
230
|
-
|
|
231
|
-
`provision` re-mints an application's development database credential, where the application has a development database, and its development platform credential. It writes the local run's settings into the environment file: `APP_DATABASE_URL`, `APP_DATABASE_CONNECTION_LIMIT`, `TURNZERO_CLOUD_TOKEN`, `APP_ENVIRONMENT`, `TURNZERO_CLOUD_API`, `TURNZERO_CLOUD_GATEWAY_URL`, and `TURNZERO_CLOUD_APPLICATION`. The first two are written only where the application has a development database. An existing file keeps every line the command does not set, and `provision` writes no `PORT`.
|
|
232
|
-
|
|
233
|
-
`provision` reads its credential in one order: a grant piped on its standard input, then a minted token in `TURNZERO_CLOUD_MINTED_TOKEN`, then this computer's token for the address from its credential file. Where none of the three holds one, the run ends with status 3 before any request, in a sentence that names all three.
|
|
234
|
-
|
|
235
|
-
The command writes the file whole under another name beside it, the environment file's name with `.turnzero-cloud-writing` after it, and renames that file into place, so a run that fails leaves the environment file as it was. An existing environment file keeps its permission mode. The command tries the write before it re-mints anything, so a file it cannot write ends the run with status 3 while the credentials are still valid. It removes the file beside the environment file where the run ends before the rename, and where an interrupt ends the run.
|
|
236
|
-
|
|
237
|
-
Each run revokes the development credentials the application had before it. A deployed development environment holds the revoked values until it restarts, so call `restart_application` on development afterwards. Its redeploy takes both re-minted credentials from custody, the connection string and the platform credential, and spends no deploy of the day. `provision` prints each credential setting as a count of its characters, never the value, and each request follows no redirect. A run makes each re-mint once and never repeats it, because the first request may have reached the platform.
|
|
238
|
-
|
|
239
|
-
Where a run ends after a re-mint without writing its value, the printed sentence names the run that re-mints again. Under a grant, that is a fresh line from a `submit_manifest` call naming `local_run`. Under a token, it is the same line again.
|
|
240
|
-
|
|
241
|
-
### run
|
|
242
|
-
|
|
243
|
-
`run` starts the application with `npm start` in the folder `--path` names. The application receives the shell's environment with every setting of the environment file laid over it, the file's line winning. `--port` sets `PORT` over both, and `TURNZERO_CLOUD_MINTED_TOKEN` and `TURNZERO_CLOUD_UPLOAD_GRANT` are left out. So is `npm_config_yes` where it holds `true`, which npm sets for the line's `-y`, so an `npx` the application runs asks before it installs, as in your shell. An `npm_config_yes` line in the environment file still reaches the application.
|
|
244
|
-
|
|
245
|
-
`run` runs until the application ends, so a tool starts it as a background process and reads its lines; its help and its first line say so. Its port line names where `PORT` comes from: `--port`, the environment file, or the shell. Where the value is a whole number from 1 to 65535, the line gives it and the address `http://localhost:<port>/`, and otherwise names the source alone. Where nothing sets `PORT`, it says the application chooses its own port, which its own lines may name. `PORT`'s value, where it is a port number, is the one value of a setting `run` prints.
|
|
246
|
-
|
|
247
|
-
The command reads the file by these forms only: `NAME=value`, with an optional `export` before the name, a comment that opens with `#`, or an empty line. A value is everything after the first `=` to the end of its line, with the spaces and tabs at its two ends dropped. One pair of matching quotes around the whole value is dropped, and nothing else in a value is interpreted: no escape, no `$` expansion, and no comment, so a `#` after a value is part of the value. A file that is not there is read as no settings. A line of another form, or a folder with no `package.json`, ends the run with status 3 before anything starts.
|
|
248
|
-
|
|
249
|
-
The application's output passes through, its standard output to standard output and its standard error to standard error. The command replaces a credential the application prints with its setting's name between angle brackets. It replaces the value of `TURNZERO_CLOUD_TOKEN` and of `APP_DATABASE_URL`. For every setting whose value is a connection string that contains a password, it replaces the whole value and the password, as the value writes it or with its percent escapes read. The values are the ones the application receives, whether the environment file or the shell set them. The command finds no value printed in any other form, and replaces nothing shorter than eight characters. The application reads no standard input.
|
|
250
|
-
|
|
251
|
-
While the application runs, an interrupt does not end the command before the application ends. A terminal passes an interrupt to the application itself. On macOS and Linux a termination or a hang-up is passed on to the application as it is. The command passes a first interrupt on only where its standard input is not a terminal, since a terminal hands it to the application itself, and a second interrupt on as a termination. On Windows the command passes nothing on: the application runs on the command's console, which hands it each interrupt itself. After an interrupt there, cmd asks `Terminate batch job (Y/N)?` once where the line was started through `npx.cmd`, as `npx` is in cmd, after the command has ended: answer `N` or `Y` and press Enter, and either returns your prompt. After `N` the line ends with the command's status, and after `Y` with cmd's own. The command's last line after an interrupted run says that cmd may ask. It follows an empty line, so it starts on a line of its own whether cmd's question comes before it or after it. The question is `npx.cmd`'s own. The command adds none: it runs npm's entry file with Node.js and not `npm.cmd`. Only where it finds that file neither beside Node.js nor beside the npm that ran it does it start npm through cmd, which then asks once more and waits for no answer. A shell whose `npx` is not a batch file asks nothing: Git Bash, or PowerShell where scripts may run, with `npx` in place of `npx.cmd`. A tool that ends the command's process outright, with no console interrupt, leaves the application running on Windows: end it by its port or in Task Manager.
|
|
252
|
-
|
|
253
|
-
### scaffold
|
|
254
|
-
|
|
255
|
-
`scaffold` writes a new service from a template into a project and tests it. The line, in its macOS and Linux form, run at the project's root:
|
|
256
|
-
|
|
257
|
-
```text
|
|
258
|
-
npx -y turnzero@latest scaffold
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
The command has three templates. A line that names no `--template` writes `hello-world`, the smallest service that deploys. `--template database-service` writes a notes service that keeps its notes in the platform's database. `--template scheduled-job` writes the `hello-world` service with one handler the platform runs each hour. The default stays `hello-world`: a template added later never becomes the default. A name the command does not have ends it with status 3, and the printed sentence lists the templates. `--path` names the root where the line runs elsewhere, and the command makes that folder where it does not stand. On Windows, a path written into the line holds none of the characters `&`, `|`, `<`, `>`, `^`, and `%`: where yours holds one, run the line from that folder without `--path`. The command reads no credential.
|
|
262
|
-
|
|
263
|
-
A line that names no `--template` prints a `template:` line before the files it wrote. It says the command wrote `hello-world` because the line names no template, and that the section Starting a new service of the command's page says what to do where another template was meant.
|
|
264
|
-
|
|
265
|
-
`hello-world` writes seven files under `app/`: `package.json`, `manifest.json`, `src/server.mjs`, `src/main.mjs`, `test/hello.test.mjs`, `.gitignore`, and `AGENTS.md`. Its server answers `GET /health` with status 200 and `{"ok":true}`, `GET /api/hello` with status 200 and the text `hello world`, and any other request with status 404. It listens on `PORT`, or on 8080 where that is not set, and its two tests read the two routes. It takes no library entry, so a `hello-world` run sends no request.
|
|
266
|
-
|
|
267
|
-
`scheduled-job` writes eight files under `app/`: `package.json`, `manifest.json`, `src/server.mjs`, `src/main.mjs`, `src/jobs.mjs`, `test/job.test.mjs`, `.gitignore`, and `AGENTS.md`. `src/jobs.mjs` holds the handler. Its manifest declares one schedule, `heartbeat`, whose handler is at `/jobs/heartbeat`, and its package file declares the Schedule package's copy at `file:lib/schedule`. Its server answers the same two routes as `hello-world`'s, and ahead of them the Schedule package's router answers the schedule's path. The handler prints one line naming the schedule and the run's key. Its four tests read the two routes, fire the schedule through the package's test double, and check that the schedule's path refuses a request without the platform's headers. The schedule is due once an hour, at the minute of the hour, in UTC, at which the run started. The command writes that minute into the manifest's cron, so the services written from the template are not all due at the same moment.
|
|
268
|
-
|
|
269
|
-
The resource is `database-service`'s alone. To keep a resource other than notes, add `--resource` with its plural, the word of the table and the route, such as `--resource orders`. `--singular` names the singular, the word for one row. Without `--singular`, the singular is the plural without its closing `s`, so a plural that does not end in `s` needs it: `--resource people --singular person`. Each name is a lower-case ASCII letter followed by lower-case ASCII letters and digits, at most 30 characters. Under a template that keeps no resource, `hello-world` and `scheduled-job`, either option ends the command with status 3 before it writes anything.
|
|
270
|
-
|
|
271
|
-
The command then writes the same files with the resource's names in place of notes, note, Notes, and Note, in one pass over each file's path and text. So a name that contains another, such as `footnotes`, is written once. `addNote` becomes `addOrder`, the table `"notes"` becomes `"orders"`, and `test/notes.test.mjs` becomes `test/orders.test.mjs`. A line that names neither a resource nor a field list writes the files exactly as the command carries them.
|
|
272
|
-
|
|
273
|
-
The command ends with status 3 before it sends any request, and writes nothing, where a name is outside that form or the plural is `health`, the template's own route. It does the same where the plural has no closing `s` and no `--singular`, where the plural is `s` alone, and where `--singular` comes without `--resource`. The printed sentence names the option and what it takes.
|
|
274
|
-
|
|
275
|
-
To start from your own columns, add `--fields` with a list of fields separated by commas, each a name, a colon, and a kind: `--fields "name:text,message:text"`. The command then writes the migration, the data layer, the routes, and the tests under those columns, in place of the one `title` column. Write the list between double quotes, because PowerShell reads a bare comma as splitting an argument.
|
|
276
|
-
|
|
277
|
-
A name is a lower-case ASCII letter, then lower-case ASCII letters, digits, and underscores, at most 30 characters, and never `id`, the key the migration writes. The kinds are `text`, which refuses an empty string, `integer`, `boolean`, and `timestamp`. Every column is required, so `POST` answers status 400 to a body that lacks a field, or whose value the database refuses for its kind. A list holds from one to twenty fields, no two under one name.
|
|
278
|
-
|
|
279
|
-
Without `--fields`, the service keeps one `text` column, `title`. `--fields` goes with `database-service` alone: another template refuses it, writes nothing, and ends with status 3, as it refuses `--resource`. A list the command cannot read ends the same way, and the printed sentence names the option, what it takes, and the four kinds.
|
|
280
|
-
|
|
281
|
-
The command starts a new application and writes over none. Where the root's `app/` holds any file or folder, it refuses and writes nothing. Under `hello-world`, the refusal is that one line. Under `database-service` and `scheduled-job`, a second line gives the `library take` line, which adds the Database or the Schedule package to the application that stands. The second line also names the page to follow: the guide Add a database for `database-service`, and the Schedule package's page for `scheduled-job`. The command takes no option that overwrites, and it asks no question. It reads no other file at the root but `system.json`, and changes no file that stands there, a `package.json` among them.
|
|
282
|
-
|
|
283
|
-
For `database-service`, the command takes the Database entry as `library take` does, and for `scheduled-job` the Schedule entry. It reads the entry's file list and each file, and checks each file's SHA-256 and the entry's closure hash before it writes anything. For `hello-world`, it reads the library folder as it stands, with no request, and refuses that folder where `library take` would, in a sentence of its own. A root that holds neither `system/` nor `system.json` takes a `system/` of its own, whatever the folder above it holds. The command then writes the template whole into `app.scaffold` beside `app/` and renames it to `app/`, so `app/` holds the template whole or none of it. An earlier run's files there under the same names are replaced. Something else standing at `app.scaffold`, such as an earlier run's files under another template, resource, or field list, is refused and never removed, and the refusal names the folder to move or remove. Next, where no `AGENTS.md` stands at the root, it writes one there, of one sentence. Last, for a template that takes an entry, it writes the entry's row in the library folder's `manifest.json`, the entry's folder, and the copy, at `app/lib/database` or `app/lib/schedule`.
|
|
284
|
-
|
|
285
|
-
The files under `app/` are these nine for the notes service: `package.json`, `manifest.json`, `migrations/0001_notes.sql`, `src/db.mjs`, `src/server.mjs`, `src/main.mjs`, `test/notes.test.mjs`, `.gitignore`, and `AGENTS.md`. That list is `database-service`'s, and the paragraphs above list `hello-world`'s seven files and `scheduled-job`'s eight. The command writes each file as it carries it, under the resource's names and the field list where the line names them, except `manifest.json`. Under every template, it fills that file's `packages` member with one row for each entry the library folder holds. Under `scheduled-job` it also writes the minute into the schedule's cron. Where an earlier run's `manifest.json` stands at `app.scaffold` with another minute in its cron, from 0 to 59, it is that run's and is replaced. A cron there that holds anything else is not the command's, and the run is refused.
|
|
286
|
-
|
|
287
|
-
`app/AGENTS.md` tells a coding tool that the service runs on Turn Zero Cloud and where the platform serves its rules. A tool started at the project's root reads the root's `AGENTS.md` first. So the command writes one there, only where none stands there, with one sentence: "The service in `app/` runs on Turn Zero Cloud: read `app/AGENTS.md` before you work on it."
|
|
288
|
-
|
|
289
|
-
Where something stands at the root's `AGENTS.md`, the command changes nothing there and prints a `not changed:` line with the sentence to add. Where the write fails, it prints a `write failed:` line with the same sentence, since a part of the file may stand. Where something stands at the root's `CLAUDE.md`, it prints a `not changed:` line for that file: Claude Code reads it and then no `AGENTS.md` by itself, so add the sentence to it. The command reads neither file, and writes no `CLAUDE.md`.
|
|
290
|
-
|
|
291
|
-
It then runs `npm install` and `npm test` in `app/`. Each receives neither `TURNZERO_CLOUD_MINTED_TOKEN` nor `TURNZERO_CLOUD_UPLOAD_GRANT`. An interrupt reaches npm, the command ends after it, and after an interrupted install the tests are not started. On Windows the command starts npm as `run` does, by npm's entry file with Node.js, and after an interrupt a line says that cmd may ask `Terminate batch job (Y/N)?`. A signal that arrives after the command's first write and before npm starts is acted on once the writes are made. The command then prints the way on, starts no npm, and ends with status 128 plus the signal's number.
|
|
292
|
-
|
|
293
|
-
A line that names no `--template` first prints its `template:` line. The command then prints a `written:` line for each file it writes, and a `not changed:` line for a file at the root it leaves as it stands. Where the write of the root's `AGENTS.md` fails, it prints a `write failed:` line. For a template that takes an entry, it then prints the take's `taken:` and `copied:` lines, which a `hello-world` run does not print. Then come npm's output, an `installed:` line, and a `tested:` line. Last, after a line that opens with `next:`, it prints the next steps.
|
|
294
|
-
|
|
295
|
-
For `database-service` the next steps are `create_application`, `submit_manifest` naming `local_run`, the provision line that call returns, the `run` line, and `deploy`. Under every template the first step, `create_application`, tells your tool to skip it where it already created the new service's application. For `hello-world` they are `create_application`, `submit_manifest` naming no `local_run`, since the service reads no setting, the `run` line, and `deploy`. After its `run` line, `GET /api/hello` answers on this machine. Under every template, the `run` step says that the line runs until the application ends, so your tool starts it as a background process and reads its lines.
|
|
296
|
-
|
|
297
|
-
For `scheduled-job` the next steps are those four, its `run` step also saying that no schedule fires on this machine and that the tests fire the handler. A fifth step calls `run_schedule` with the application, the schedule `heartbeat`, and `wait_seconds`, which fires the handler now and answers how the run ended. A settled answer carries the handler's lines in `console`, and its `more` names the `read_logs` call where the lines were cut, may still be arriving, or could not be read. An answer not yet settled carries no `console` and names `read_schedules`, which lists every run.
|
|
298
|
-
|
|
299
|
-
Where it printed a `not changed:` or a `write failed:` line, the steps open with one step for each such line, which repeats the sentence to add. Each line of the command's that it prints carries the address of the platform the run used, and `npx.cmd` on Windows.
|
|
300
|
-
|
|
301
|
-
Where the install fails or the run stops, the last printed line gives one way on, by what stands at `app`. Where the run moved the template in, the way on for `hello-world` is `npm install` and then `npm test` in `app/`. For `database-service` and `scheduled-job`, it is the `library take` line for the template's entry, run at the project's root, then `npm test` in `app/`. Where it did not, and `app/` does not stand or stands empty, it is the same line again. Where something that is no folder, or that the command cannot read, stands there, it is to move it or make it readable, then the same line again. Where `app/` holds entries that are not the run's, an application stands there. For `database-service` and `scheduled-job`, the line then names `library take` as the refusal of such a folder does, and for `hello-world` it says the scaffold writes over no application. Where the tests fail, they failed on the files as written, before any edit. The printed line then says to report it, and gives no line to run again. It names the entry and the version the library served, or for `hello-world` the template and the command's version.
|
|
302
|
-
|
|
303
|
-
### authorize
|
|
304
|
-
|
|
305
|
-
`authorize` authorizes this computer at one platform address, so a deploy from it needs no credential in its line. It takes three acts, once for each address, through the connection you signed in with:
|
|
306
|
-
|
|
307
|
-
1. `authorize` with nothing piped keeps a verifier on this computer as the address's pending request. It prints a sentence naming the address, then `challenge:` and the challenge, then `call mint_token with:` and the call's members, one to a line.
|
|
308
|
-
2. Your tool calls `mint_token` with those members: the challenge, `scope_kind` `account`, `authorized_computer` `true`, and this computer's name as the `label`.
|
|
309
|
-
3. Your tool runs the line that call returns, `echo <token code> | <command> authorize`, once, as given, on this computer. The command presents the code with the verifier and keeps the token the platform mints.
|
|
310
|
-
|
|
311
|
-
The last act prints `authorized:` with the address, the label, and the token's expiry. The pending request lasts ten minutes. Run again within them, `authorize` prints the same challenge and makes no new verifier; after them, it makes a new one and says so.
|
|
312
|
-
|
|
313
|
-
The token is account-scoped and lasts 30 days. Run `authorize` again to renew it: the command keeps the new token and revokes the one it held before. The token works from any computer until it expires or is revoked, so keep the file as you would a password. `list_tokens` shows it by its label, and `revoke_token` ends it.
|
|
314
|
-
|
|
315
|
-
The address is the one `--origin` names, else the one in `TURNZERO_CLOUD_ORIGIN`, else `https://turnzero.ai`. A `--origin` must name `https://turnzero.ai` or the address in that variable, and an address on your own machine only where the variable names it. Any other ends the command with status 3 before anything is sent.
|
|
316
|
-
|
|
317
|
-
The credential file is `credentials.json` in a folder `turnzero-cloud`. On macOS and Linux it stands under the folder `XDG_CONFIG_HOME` names, or under `.config` in your home folder where that variable is not set. On Windows it stands under the folder `LOCALAPPDATA` names, never in the roaming profile.
|
|
318
|
-
|
|
319
|
-
The file is yours, outside every project. On macOS and Linux the command makes the folder and the file readable by you alone, and on Windows the profile's own permissions limit the folder to you, the system, and administrators. Any program that runs as you can still read it, your application under `run` among them.
|
|
320
|
-
|
|
321
|
-
The command writes the file whole into a file beside it and renames it into place, so two runs at once leave one whole file. It refuses a file not of the form it writes by its path, never printing its content: move that file aside and authorize this computer again.
|
|
322
|
-
|
|
323
|
-
### logout
|
|
324
|
-
|
|
325
|
-
`logout` ends this computer's authorization at one address. It revokes the token at the platform under the token itself, removes the token and any pending request from the credential file, and prints `logged out:` with the address and the token's identifier. Its address is the one `--origin` names, else the one in `TURNZERO_CLOUD_ORIGIN`, else `https://turnzero.ai`.
|
|
326
|
-
|
|
327
|
-
Where the platform cannot be reached or refuses, `logout` removes both all the same, says the token stands until it expires, and names `revoke_token` with the identifier. Where the file holds nothing for the address, it says so and ends with status 0.
|
|
328
|
-
|
|
329
|
-
### token
|
|
330
|
-
|
|
331
|
-
`token request` and `token claim` mint a token that is not this computer's, such as a CI job's, whose value passes through no AI tool. `token request` is the first act: it keeps a verifier, as `authorize` does, and prints the challenge and a `mint_token` call naming it. The task names the token's scope, application, grants, label, and expiry beside it.
|
|
332
|
-
|
|
333
|
-
`token claim` is the last act, and it is yours to run, in a terminal outside the AI tool, on the same computer and as the same user. It reads the token code the answered line pipes in, presents it with the verifier, and prints the token's value once, on standard output. Every other line goes to standard error, among them a line that opens with `claimed:`.
|
|
334
|
-
|
|
335
|
-
So a pipe after the line, such as `| gh secret set TURNZERO_CLOUD_MINTED_TOKEN`, takes the value alone. `token claim` runs only where its standard error is a terminal, which yours stays when you pipe its standard output, and a tool's shell does not. Anywhere else it reads nothing, sends nothing, and leaves the code live.
|
|
336
|
-
|
|
337
|
-
## Options
|
|
338
|
-
|
|
339
|
-
Every subcommand's usage line, its options, and the statuses it ends with are on https://turnzero.ai/cloud/reference/turnzero-command/, generated from the command's own sources. `--help` prints the same usage on your machine.
|
|
340
|
-
|
|
341
|
-
An option's value that opens and closes with a double-quote character is read without that pair, since a shell on Windows can leave the quotes in place.
|
|
342
|
-
|
|
343
|
-
## What it reads
|
|
344
|
-
|
|
345
|
-
- The credential, in this order and no other way:
|
|
346
|
-
- a grant from standard input, as the line the tool's call returns pipes it in, read to the input's end within ten seconds; `deploy` and `check` read nothing there;
|
|
347
|
-
- then, under `deploy`, `check`, and `provision` only, the minted token in `TURNZERO_CLOUD_MINTED_TOKEN`; under `secret`, a set variable with no grant piped ends the run before any request;
|
|
348
|
-
- then, under `deploy`, `check`, `provision`, and `secret` only, this computer's token for the address, from the credential file.
|
|
349
|
-
- The token code, under `authorize` and `token claim`, read from standard input as a grant is read.
|
|
350
|
-
- Standard input, under every subcommand that reads it, read to its end within ten seconds. Input that sends some bytes and does not end in that time, or that cannot be read to its end, ends the run before any request, since what arrived may not be whole. So does input longer than any grant or code can be. Under `provision` and `authorize`, where nothing piped has a meaning, the refusal of input that failed before it sent anything also says how to run with nothing piped. Input that ends, or reaches ten seconds, having sent nothing counts as nothing piped.
|
|
351
|
-
- The credential's handling. A value of the wrong form ends the command before any request, and a value on standard input that is not of its form ends it without a read of the token's variable. The command takes the credential it runs under in none of its arguments. The one credential it keeps on disk is this computer's token, in the credential file. It prints no credential but the one value `token claim` prints to your own terminal. `deploy` never reads `TURNZERO_CLOUD_TOKEN`.
|
|
352
|
-
|
|
353
|
-
The command sends a credential only to an `https` address or to an address on your own machine, and no request that carries a credential follows a redirect. It sends a minted token only to `https://turnzero.ai` or to the address in `TURNZERO_CLOUD_ORIGIN`, an address on your own machine only where that variable names it.
|
|
354
|
-
|
|
355
|
-
- The application's folder, under `hash`, `deploy`, and `check`, which must contain `package.json` at its top. The zip leaves out every `node_modules` and `.git` entry and every `.env` and `.env.*` file, whatever the case of their names. The command refuses a symbolic link it would otherwise include, and a folder whose zip would contain more than 65,535 files. Every version of the command builds the same zip from the same folder on the same Node.js version, so a hash printed by one version matches the upload of another.
|
|
356
|
-
- The application's Git commit, under `deploy` alone. Where the folder is inside a Git repository, the command reads the commit checked out there from Git's own files, with no `git` program needed. It sends that commit with the start, and the platform keeps it with the version it deploys. Uncommitted changes are not part of it. Where `--path` names a link to a folder, the commit is read where the link points, from the folder the zip is built from. A Git file that names a network or device location, such as `\\server\share`, is not followed, so no credential is offered to another computer, and no commit is sent. Where no commit can be read, or `--path` names a `.zip` file, the command sends none and the deploy goes on as before.
|
|
357
|
-
- The files each subcommand is given: the file `--path` names under `put`, the file `--value-file` names under `secret`, and the environment file under `provision` and `run`.
|
|
358
|
-
- `TURNZERO_CLOUD_MINTED_TOKEN`: a minted token, set for the one line: by a job under `deploy`, `check`, or `provision`, and by a tool connected by a minted token under `deploy` and `check`.
|
|
359
|
-
- `TURNZERO_CLOUD_ORIGIN`: under `deploy`, `check`, and `provision`, the platform's address the minted token is sent to where the line names no `--origin`, set beside the token by the job or the tool that holds it. An address on the machine itself is allowed only where this variable names it.
|
|
360
|
-
- `TURNZERO_DEPLOY_NO_WAIT`: under `deploy`, with any value, the command returns once the deploy has started.
|
|
361
|
-
- `TURNZERO_CLOUD_USER_AGENT`: where set, its value, in printable characters only, is added to the user agent the command sends, `turnzero/<version>`.
|
|
362
|
-
|
|
363
|
-
## What it prints, and how it ends
|
|
364
|
-
|
|
365
|
-
`hash` prints `sha256:` followed by the hash in 64 lower-case hexadecimal characters on its first line. For a folder with nothing more to report, and without `--list`, it is the only line. With `--list`, the lines below are followed by one line for each file the zip holds, in the zip's order: `file:`, the size in bytes, and the name, whole.
|
|
366
|
-
|
|
367
|
-
Four more lines each print only where they apply. A line that opens with `left out:` names the paths the zip left out, relative to the folder, a folder with a closing slash. It names at most ten of them and then the count of the rest. A line that opens with `warning:` names each `.zip` file at the top of the folder, which the upload includes.
|
|
368
|
-
|
|
369
|
-
A second `warning:` line names each file that looks like a key or a credential, by its name or by a private key written as text inside it. It never shows what a file holds. A third `warning:` line names the health path of `manifest.json` where no other file in the zip contains the path's last segment, in its text or in its own path. The path `/` draws none, and the path is printed without its query. The warning refuses nothing, and `deploy`'s refusal before the upload reads the recorded manifest's path instead.
|
|
370
|
-
|
|
371
|
-
For this warning the command sets aside package files and documentation: every `package.json`, the lock files `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, and `pnpm-lock.yaml`, and every file whose name ends `.md`, `.markdown`, `.txt`, or `.rst`. A `README.md` or a package description that names the path therefore does not stop the warning.
|
|
372
|
-
|
|
373
|
-
A file with one of those endings still counts where its own path ends with the whole health path, such as `public/health.txt` for `/health.txt`. A name in these lines has each character you would not see replaced by a percent escape, and is cut short past 80 characters.
|
|
374
|
-
|
|
375
|
-
`deploy` prints a `zip:` line ending with the same hash, then the `left out:` line, the `.zip` warning, the warning for a key or a credential, and the health path warning where they apply.
|
|
376
|
-
|
|
377
|
-
Then, before the upload starts, it prints a `prepared:` line with the upload's identifier and when its grant expires. Where the environment runs no version yet and no file of the folder's zip names the recorded health path, it then prints the platform's refusal and `Nothing was uploaded and nothing was started.`, and ends with status 3. Otherwise it prints an `uploaded:` line and a `started:` line with the platform's response to the start. Then it prints each line of the deploy's progress as it arrives: each step, the outcome, and on a failure the platform's reading of its cause.
|
|
378
|
-
|
|
379
|
-
The wait makes at most 450 reads of at most 60 seconds each. A read answered with status 502, 503, or 504 met a failure that is often temporary, and the command prints a line that says so. It makes the read again after 2, then 4, then 8 seconds, at most three more times for one read, each counted among the 450. A read that still fails ends the wait with status 2.
|
|
380
|
-
|
|
381
|
-
`check` prints the `zip:` line `deploy` prints. After the platform's answer, it prints the lines `deploy` prints after its `zip:` line, from `files:` on. It leaves out the health path warning where the deploy would be a first one, since a `refused:` line then reads the recorded health path. A call that gets no usable response prints none of these lines.
|
|
382
|
-
|
|
383
|
-
Then `check` prints one line that opens with `refused:` for each refusal the platform answered, in its order, then one for each refusal of the zip. Each names the refusal and gives the platform's own explanation. Where the zip's layout passes its checks and its `manifest.json` names another health path than the recorded manifest, a line that opens with `manifest:` names both and says to call `submit_manifest` with the zip's copy first. A last line that opens with `checked:` counts the refusals.
|
|
384
|
-
|
|
385
|
-
A refusal prints the platform's own name and explanation, and the preparing call's refusals print under the act `prepare`. Under this computer's token, a refusal closes by saying the credential was this computer's token, and that `authorize` authorizes the computer again. A refusal of the command's own names the option and never repeats the value it was given.
|
|
386
|
-
|
|
387
|
-
`authorize` prints the first act's lines, or `authorized:`. `logout` prints `logged out:`. `token request` prints the first act's lines, and `token claim` the value alone on standard output and a `claimed:` line on standard error.
|
|
388
|
-
|
|
389
|
-
No line the command prints holds a grant, a token code, a verifier, a token, or a secret's value, except the one value line `token claim` prints to your own terminal.
|
|
390
|
-
|
|
391
|
-
The statuses mean the same under every subcommand except `run`. `run` ends with the application's own status, whatever it is, so a status under `run` may be the application's and not the command's. Where a signal ended the application, the status is 128 plus the signal's number. After an interrupt on Windows, the status is npm's, or cmd's where the command started npm through cmd, and may not be the application's. Where no application was started, `run` ends with status 3 and the command's own lines say so.
|
|
392
|
-
|
|
393
|
-
- **0**: done.
|
|
394
|
-
- `hash`: the hash was printed.
|
|
395
|
-
- `deploy`: a deployed version, or, with `TURNZERO_DEPLOY_NO_WAIT` set, a deploy that started.
|
|
396
|
-
- `check`: none of the checks would refuse a deploy now.
|
|
397
|
-
- `secret`: the value was written.
|
|
398
|
-
- `put`: the file was written.
|
|
399
|
-
- `export download`: every file the manifest names is on disk, with any moved file reported.
|
|
400
|
-
- `library take`: the entry was taken, and installed where it carries compiled modules.
|
|
401
|
-
- `provision`: the settings were written.
|
|
402
|
-
- `run`: the application ended with status 0.
|
|
403
|
-
- `scaffold`: the files were written and installed, the template's entry was taken where it takes one, and the tests passed.
|
|
404
|
-
- `authorize`: the challenge was printed, or this computer was authorized.
|
|
405
|
-
- `logout`: the entries were removed and the token was revoked or had ended, or none was kept.
|
|
406
|
-
- `token`: the challenge was printed, or the value was printed once.
|
|
407
|
-
- **1**: the act ran and failed, in whole or in a part the printed lines name.
|
|
408
|
-
- `deploy`: the deploy failed.
|
|
409
|
-
- `check`: a deploy would be refused now, and the `refused:` lines name each refusal.
|
|
410
|
-
- `export download`: a file failed, was cut short, or was refused, and running the line again makes its read again. Where a file was answered as an absent name, the closing lines name a fresh export.
|
|
411
|
-
- `library take`: the entry, its row, and the copy were written, and `npm install` failed.
|
|
412
|
-
- `provision`: the settings were written without a connection limit, which the platform's answer did not carry.
|
|
413
|
-
- `scaffold`: the files were written, and `npm install` or the tests failed.
|
|
414
|
-
- `authorize`: a token was minted and not kept, or the token this computer held before was not revoked. The printed lines name `revoke_token`.
|
|
415
|
-
- `logout`: the platform refused the revocation, or the credential file could not be written after it. The printed lines name `revoke_token`.
|
|
416
|
-
- `token`: the token minted was an authorized computer's, and it was revoked where it could be.
|
|
417
|
-
- **2**: the outcome is unknown, or the run stopped before its end, and the printed sentence names the call that reads the outcome or the line to run next. The command also ends with status 2 where it stops on an error of its own, and its last line says so.
|
|
418
|
-
- `deploy`: the command stopped waiting, or the start got no response or the platform failed while responding to it. The deploy may still be running, and `read_status` reads it.
|
|
419
|
-
- `secret`: the write got no response, or an answer that is not a refusal. `list_secrets` shows when the name was last written.
|
|
420
|
-
- `put`: the upload got no response, or an answer that is not a refusal. The file may have landed, and a fresh line writes it again.
|
|
421
|
-
- `export download`: the run stopped before the end, and a fresh line from `mint_download_grant` resumes it.
|
|
422
|
-
- `provision`: a credential was re-minted, or may have been, and its value was not written. The printed sentence names the run that re-mints again.
|
|
423
|
-
- `scaffold`: the run stopped before its end, by an interrupt or another signal that ended npm, by an error of the command's own, or by something that came to stand at `app` while it wrote. The last printed line names the way on.
|
|
424
|
-
- `authorize` and `token`: the exchange got no response, or an answer that is not a refusal. `list_tokens` shows whether a token was minted.
|
|
425
|
-
- `logout`: the revocation got no response, or an answer that is not a refusal. `list_tokens` shows whether the token stands.
|
|
426
|
-
- **3**: nothing was started, and the printed refusal or sentence names the call to make next.
|
|
427
|
-
- `hash`: no hash was printed.
|
|
428
|
-
- `deploy`: an option, a variable, the path, or the credential was refused. Or the folder had no `package.json`, contained a symbolic link, or had too many files. Or the preparing call was refused or returned no upload the command can use, the upload or the start was refused, or the upload got no response. Or no file of the zip names the health path a first deploy checks. Or no credential was read, and the command printed how to authorize this computer. The way on is usually the same line again.
|
|
429
|
-
- `check`: nothing was checked. An option, the path, or the credential was refused, or no credential was read and the command printed how to authorize this computer. Or the `check_deploy` call was refused, got no response, was redirected, or was answered by a failure. The way on is usually the same line again.
|
|
430
|
-
- `secret`, `put`, and `library take`: nothing was written.
|
|
431
|
-
- `export download`: an option, the grant, the folder, or the manifest was refused, and nothing was written.
|
|
432
|
-
- `provision`: nothing was re-minted.
|
|
433
|
-
- `run`: no application was started.
|
|
434
|
-
- `scaffold`: nothing was written.
|
|
435
|
-
- `authorize` and `token`: nothing was minted. An option, the credential file, or the token code was refused, no request was pending, or the exchange was refused; under `token claim`, also a standard error that is no terminal.
|
|
436
|
-
- `logout`: nothing was sent or removed, since an option or the credential file was refused.
|
|
437
|
-
|
|
438
|
-
Under every subcommand, a Node.js older than 24 ends the command with status 3 before it reads its arguments or standard input, as How it runs says.
|
|
28
|
+
Every subcommand's options, statuses, and output are on the reference page: https://turnzero.ai/cloud/reference/turnzero-command/
|
|
439
29
|
|
|
440
30
|
## Licence
|
|
441
31
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "turnzero",
|
|
3
|
-
"version": "0.12.
|
|
3
|
+
"version": "0.12.1-next.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "The Turn Zero Cloud command, which an AI tool runs on your machine to deploy an application, store a secret, upload a file, download an export, take a library entry, write a local run's settings, start the application locally, and scaffold a new service from a template.",
|
|
6
6
|
"license": "Apache-2.0",
|