@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 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>;
@@ -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 {};