@singularity-layer/cli 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/LICENSE +21 -0
- package/README.md +133 -0
- package/dist/auth.d.ts +111 -0
- package/dist/bundle.d.ts +42 -0
- package/dist/cli.d.ts +16 -0
- package/dist/cli.js +1038 -0
- package/dist/format.d.ts +28 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +309 -0
- package/dist/processors.d.ts +10 -0
- package/dist/version.d.ts +11 -0
- package/package.json +78 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Event Horizon Labs
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# `singularity` — Singularity developer CLI
|
|
2
|
+
|
|
3
|
+
Build on the Singularity Cloud Network from your terminal.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm i -g @singularity-layer/cli
|
|
7
|
+
singularity --help
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Requires Node 20+ and a Solana keypair (`solana-keygen new`). No account, no API key, no dashboard
|
|
11
|
+
login — your wallet *is* the account.
|
|
12
|
+
|
|
13
|
+
## Processors
|
|
14
|
+
|
|
15
|
+
A Processor is a loop you write; we host it, run it on demand, and buyers pay **you** directly per
|
|
16
|
+
call. There is no platform cut and we never custody your money: an x402 payment is a USDC transfer
|
|
17
|
+
from the buyer's wallet to yours.
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
mkdir my-loop && cd my-loop
|
|
21
|
+
singularity processors init my-loop # scaffolds processor.json + processor.js
|
|
22
|
+
singularity processors deploy # prints the invoke token ONCE
|
|
23
|
+
singularity processors run '{"hi":1}' # invoke it, print the output
|
|
24
|
+
singularity processors publish # instantly public — no review step
|
|
25
|
+
singularity processors logs # runs + failure rate
|
|
26
|
+
singularity processors revenue # sales and compute spend, everything you own
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Your loop is a standard Worker module:
|
|
30
|
+
|
|
31
|
+
```js
|
|
32
|
+
export default {
|
|
33
|
+
async fetch(request) {
|
|
34
|
+
const { input } = await request.json();
|
|
35
|
+
// Call APIs and models with fetch(). Credentials for the hosts you declared
|
|
36
|
+
// are injected for you, so no keys belong in this file.
|
|
37
|
+
return Response.json({ ok: true, received: input });
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### TypeScript and npm packages
|
|
43
|
+
|
|
44
|
+
Add `--bundle` (or `"$bundle": true` in `processor.json`) and the CLI runs esbuild locally, so
|
|
45
|
+
`import` and npm dependencies work:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npm i zod
|
|
49
|
+
singularity processors deploy --bundle --entry processor.ts
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**The bundling happens on your machine, on purpose.** We never run `npm install` for you: a
|
|
53
|
+
postinstall script is arbitrary code, and running it on infrastructure that holds platform
|
|
54
|
+
credentials is not something scanning makes safe. Your bundle crosses the boundary; your
|
|
55
|
+
`node_modules` never does.
|
|
56
|
+
|
|
57
|
+
The bundler targets a Worker isolate, so a dependency reaching for `fs`, `child_process` or raw
|
|
58
|
+
sockets fails **here**, on your terminal, naming the importer — instead of dying inside a run a buyer
|
|
59
|
+
has already paid for.
|
|
60
|
+
|
|
61
|
+
Going back to a single file needs `--no-bundle`, because a stored bundle keeps winning at load time
|
|
62
|
+
and plain `code` would silently never take effect.
|
|
63
|
+
|
|
64
|
+
### Invoking
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
singularity processors run '{"n":10}' # JSON in, output out
|
|
68
|
+
singularity processors call -i # prompts per field, from your own input_schema
|
|
69
|
+
singularity processors schema # what buyers and agents see
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Secrets
|
|
73
|
+
|
|
74
|
+
Declare a secret in `processor.json`, then set its value:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
singularity processors secrets OPENAI_API_KEY=sk-...
|
|
78
|
+
singularity processors env list # which are declared, which are set
|
|
79
|
+
singularity processors env unset OPENAI_API_KEY
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Values are write-only. They are never returned — not to you, not to your code — and the egress
|
|
83
|
+
gateway injects them into outbound requests to the host you bound them to.
|
|
84
|
+
|
|
85
|
+
### Turning it off without losing it
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
singularity processors pause # buyers and token callers refused; no payment is taken
|
|
89
|
+
singularity processors resume
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`pause` is the switch to reach for when an upstream key hits its quota or a loop misbehaves.
|
|
93
|
+
Unlisting only hides you from the catalogue — the endpoint keeps answering anyone with the URL — and
|
|
94
|
+
`delete` burns the slug forever. While paused you can still invoke it yourself with your wallet, so
|
|
95
|
+
you can verify a fix before resuming.
|
|
96
|
+
|
|
97
|
+
### For scripts and agents
|
|
98
|
+
|
|
99
|
+
Every command takes `--json`:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
singularity processors list --json | jq '.processors[] | select(.paused_at)'
|
|
103
|
+
singularity processors run '{"n":1}' --json
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Auth
|
|
107
|
+
|
|
108
|
+
A per-request Solana wallet signature, using `~/.config/solana/id.json` by default (`--keypair
|
|
109
|
+
<path>`, `SINGULARITY_KEYPAIR`, or `singularity processors configure` to change it). **The key never
|
|
110
|
+
leaves your machine** — only a signature is sent, and it covers the method, the path and a hash of the
|
|
111
|
+
body, so it authorizes exactly one request and cannot be replayed against another.
|
|
112
|
+
|
|
113
|
+
## Programmatic use
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
import { bundleProcessor, api, loadKeypair, usd } from '@singularity-layer/cli';
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
The exported pieces are the ones that are easy to get subtly wrong: the signature scheme, the
|
|
120
|
+
micro-USDC formatting (never use floats for money — the ledger is integers), and the bundler
|
|
121
|
+
configuration. Subcommands are deliberately not exported; they call `process.exit`.
|
|
122
|
+
|
|
123
|
+
## The other Singularity CLIs
|
|
124
|
+
|
|
125
|
+
These are separate on purpose — different audiences, different runtimes.
|
|
126
|
+
|
|
127
|
+
| CLI | Who it's for |
|
|
128
|
+
|---|---|
|
|
129
|
+
| `singularity` | Developers building on the platform |
|
|
130
|
+
| [`sglcode`](https://www.npmjs.com/package/sglcode) | Agentic coding on the grid |
|
|
131
|
+
| `sgl` | Node operators running compute and earning |
|
|
132
|
+
|
|
133
|
+
New capabilities here become **subcommands**, never new binaries.
|
package/dist/auth.d.ts
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Wallet signing and the signed HTTP client.
|
|
3
|
+
*
|
|
4
|
+
* Shared by every subcommand, so the signature scheme lives in exactly one place. Getting it subtly
|
|
5
|
+
* wrong produces a 401 with no explanation, which is miserable to debug from a terminal.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* EXPLICITLY ANNOTATED ON THE DECLARATION, not just on the arrow.
|
|
9
|
+
*
|
|
10
|
+
* TypeScript only narrows after a never-returning call when the *declaration* carries the type. With
|
|
11
|
+
* the annotation on the arrow alone, `if (!key) die(...)` did not narrow `key`, so every guarded use
|
|
12
|
+
* afterwards needed a redundant non-null assertion — and an assertion is exactly the thing that
|
|
13
|
+
* silently survives a later refactor that removes the guard.
|
|
14
|
+
*/
|
|
15
|
+
export declare const die: (msg: string) => never;
|
|
16
|
+
export declare const ok: (msg?: string) => void;
|
|
17
|
+
export interface Keypair {
|
|
18
|
+
secretKey: Uint8Array;
|
|
19
|
+
address: string;
|
|
20
|
+
}
|
|
21
|
+
export type Flags = Record<string, string | boolean>;
|
|
22
|
+
/**
|
|
23
|
+
* Base58 (Bitcoin alphabet), which is how Solana addresses are written.
|
|
24
|
+
*
|
|
25
|
+
* TWO PARTS, AND BOTH ARE LOAD-BEARING: the leading zero BYTES become leading '1' characters, and the
|
|
26
|
+
* remaining bytes become a base-58 number. Base58 has no digit for a leading zero, so dropping those
|
|
27
|
+
* bytes silently yields a shorter, still-valid-looking address — a different account. That is a
|
|
28
|
+
* fund-safety property, not a formatting nicety.
|
|
29
|
+
*
|
|
30
|
+
* THE ZERO CASE WAS WRONG AND A TEST FOUND IT. The value part was seeded as `[0]` and always emitted
|
|
31
|
+
* at least one digit, so an all-zero input produced one character too many: bs58([0]) returned '11'
|
|
32
|
+
* instead of '1'. Every byte was already accounted for as a leading zero, and then the zero VALUE was
|
|
33
|
+
* printed on top of them. Unreachable from a real keypair — no keypair derives an all-zero pubkey —
|
|
34
|
+
* but the fix is to stop converting the leading zeros twice, which is also what makes the encoder
|
|
35
|
+
* match every other base58 implementation on every input rather than merely on the likely ones.
|
|
36
|
+
*/
|
|
37
|
+
export declare function bs58(bytes: Uint8Array): string;
|
|
38
|
+
/**
|
|
39
|
+
* Load a Solana keypair.
|
|
40
|
+
*
|
|
41
|
+
* Defaults to the Solana CLI's location so most people need no configuration. The key never leaves
|
|
42
|
+
* the machine — only a signature is sent.
|
|
43
|
+
*/
|
|
44
|
+
export declare function loadKeypair(flags?: Flags): Keypair;
|
|
45
|
+
export interface ApiOpts {
|
|
46
|
+
body?: unknown;
|
|
47
|
+
kp?: Keypair;
|
|
48
|
+
bearer?: string;
|
|
49
|
+
/**
|
|
50
|
+
* Query parameters. An ARRAY value becomes REPEATED keys (`?tag=a&tag=b`), which is exactly what
|
|
51
|
+
* the server reassembles an array input from. Joining them into `a,b` instead would arrive as one
|
|
52
|
+
* string and, for a field whose schema says array, be delivered as `["a,b"]` — a paid run failing
|
|
53
|
+
* on input the caller sent correctly.
|
|
54
|
+
*/
|
|
55
|
+
query?: Record<string, string | number | Array<string | number>>;
|
|
56
|
+
method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
|
|
57
|
+
/**
|
|
58
|
+
* Sign the QUERY STRING as the body. GET run route ONLY — see the note in api().
|
|
59
|
+
*
|
|
60
|
+
* Not a preference. It must match, exactly, which raw string the server hashes for the route
|
|
61
|
+
* being called; getting it wrong produces a 401 with no explanation.
|
|
62
|
+
*/
|
|
63
|
+
signQuery?: boolean;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Signed request against a Singularity service.
|
|
67
|
+
*
|
|
68
|
+
* The signature covers METHOD, PATH and a hash of the BODY, so it authorizes ONE exact request and
|
|
69
|
+
* cannot be replayed against another route or with altered content.
|
|
70
|
+
*
|
|
71
|
+
* THREE THINGS HERE ARE STRUCTURAL, NOT STYLE:
|
|
72
|
+
*
|
|
73
|
+
* 1. The body is serialized ONCE into `raw`, and that same string is both hashed and sent.
|
|
74
|
+
* Serializing twice would let key order or whitespace differ, producing a valid-looking
|
|
75
|
+
* signature the server rejects as an unexplained 401.
|
|
76
|
+
*
|
|
77
|
+
* 2. `query` is kept SEPARATE from `path`. The server signs `new URL(url).pathname`, which excludes
|
|
78
|
+
* the query string — folding `?limit=50` into the path would 401 every time.
|
|
79
|
+
*
|
|
80
|
+
* 3. A GET signs the EMPTY STRING — except on the run route, where `signQuery` is set.
|
|
81
|
+
*
|
|
82
|
+
* This asymmetry is the server's, and it is mandatory rather than chosen. The run route hashes
|
|
83
|
+
* `url.search` for a GET, because a GET run's INPUT lives in the query and signing '' would leave
|
|
84
|
+
* it unauthenticated. Every other owner GET route (list, detail, runs, earnings) verifies against
|
|
85
|
+
* '' and always has — as does the live dashboard, which signs '' for GET regardless of query. So
|
|
86
|
+
* "sign the query on every GET" is the version that looks more secure and 401s in production:
|
|
87
|
+
* `logs --limit 30` would sign `?limit=30` while the server hashed ''.
|
|
88
|
+
*
|
|
89
|
+
* Found by adversarial review after I had written exactly that. The rule is: match the route.
|
|
90
|
+
*/
|
|
91
|
+
export declare function api<T = unknown>(base: string, method: NonNullable<ApiOpts['method']>, path: string, { body, kp, bearer, query, signQuery }?: ApiOpts): Promise<T>;
|
|
92
|
+
/**
|
|
93
|
+
* Parse argv into subcommand path, positional args, and flags.
|
|
94
|
+
*
|
|
95
|
+
* A flag is boolean when nothing follows it OR the next token is another flag. Missing the "nothing
|
|
96
|
+
* follows" case made a trailing `--yes` parse as undefined, so a confirmation guard could never be
|
|
97
|
+
* dismissed — found by actually running it.
|
|
98
|
+
*/
|
|
99
|
+
export declare function parseArgs(argv: string[]): {
|
|
100
|
+
words: string[];
|
|
101
|
+
flags: Flags;
|
|
102
|
+
};
|
|
103
|
+
/**
|
|
104
|
+
* Read a line from the terminal. Used by the interactive `configure` and `call -i`.
|
|
105
|
+
*
|
|
106
|
+
* UNREFS STDIN WHEN DONE, which is not decoration. `resume()` adds a libuv reference, so a process
|
|
107
|
+
* that has finished its work still has a live handle nothing will ever read from, and the command
|
|
108
|
+
* prints its result and then hangs. Unrefing lets the loop drain and exit naturally — the
|
|
109
|
+
* alternative, calling process.exit(), truncates piped stdout.
|
|
110
|
+
*/
|
|
111
|
+
export declare function prompt(question: string, fallback?: string): Promise<string>;
|
package/dist/bundle.d.ts
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Bundle a processor on the PUBLISHER's machine.
|
|
3
|
+
*
|
|
4
|
+
* This is the whole reason npm packages and multi-file TypeScript processors are possible. The
|
|
5
|
+
* alternative — accepting a package.json and running `npm install` on our infrastructure — means
|
|
6
|
+
* executing arbitrary postinstall scripts on a box that holds platform credentials. No amount of
|
|
7
|
+
* scanning makes that safe, so the bundler runs here, where the code's author already has a machine
|
|
8
|
+
* they trust and dependencies they chose.
|
|
9
|
+
*
|
|
10
|
+
* WHAT CROSSES THE BOUNDARY: one bundled module, plus the pre-bundle sources for provenance.
|
|
11
|
+
* `node_modules` never does.
|
|
12
|
+
*
|
|
13
|
+
* The target is a Cloudflare Worker isolate, so the output has to be an ES module with no Node
|
|
14
|
+
* built-ins beyond what `nodejs_compat` provides, and no filesystem or process access. esbuild is
|
|
15
|
+
* configured accordingly, and a dependency that reaches for something unavailable fails HERE — at
|
|
16
|
+
* deploy time, on the publisher's terminal — rather than as an opaque runtime error inside a paid run.
|
|
17
|
+
*/
|
|
18
|
+
/** Mirrors PROCESSOR_MAX_CODE_BYTES on the server. Failing here beats a 413 after a wallet prompt. */
|
|
19
|
+
export declare const MAX_BUNDLE_BYTES = 1048576;
|
|
20
|
+
export interface BundleResult {
|
|
21
|
+
bundle: string;
|
|
22
|
+
files: Record<string, string>;
|
|
23
|
+
meta: {
|
|
24
|
+
bundler: string;
|
|
25
|
+
entry: string;
|
|
26
|
+
bytes: number;
|
|
27
|
+
/** sha256 per source file, so "the code running is the code you wrote" is checkable later. */
|
|
28
|
+
sources: Record<string, string>;
|
|
29
|
+
};
|
|
30
|
+
warnings: string[];
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Bundle `entry` into one ES module.
|
|
34
|
+
*
|
|
35
|
+
* `minify` is off by default on purpose: the publisher reads their own errors, and a minified stack
|
|
36
|
+
* trace in a run log is worthless to them. Size is rarely the constraint at 1 MiB.
|
|
37
|
+
*/
|
|
38
|
+
export declare function bundleProcessor(opts: {
|
|
39
|
+
entry: string;
|
|
40
|
+
cwd: string;
|
|
41
|
+
minify?: boolean;
|
|
42
|
+
}): Promise<BundleResult>;
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* singularity — the Singularity developer CLI.
|
|
3
|
+
*
|
|
4
|
+
* ONE command, a subcommand per product. New capabilities become subcommands here rather than new
|
|
5
|
+
* binaries; that rule is what stops this becoming five CLIs nobody can keep straight.
|
|
6
|
+
*
|
|
7
|
+
* It is deliberately NOT the same tool as:
|
|
8
|
+
* • `sgl` — the Rust node-operator daemon. Different audience (people running GPU boxes),
|
|
9
|
+
* different runtime, and its releases are hash-allowlisted for supply-chain
|
|
10
|
+
* reasons, so folding a fast-moving dev tool into that process would slow both.
|
|
11
|
+
* • `sglcode` — the agentic coding CLI. A product in its own right, like Claude Code.
|
|
12
|
+
* Demoting it to `singularity code` would misrepresent what it is.
|
|
13
|
+
*
|
|
14
|
+
* Auth is a per-request Solana wallet signature. The key never leaves the machine.
|
|
15
|
+
*/
|
|
16
|
+
export {};
|