layerbase 0.0.3 → 0.1.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 CHANGED
@@ -1,11 +1,140 @@
1
1
  # layerbase
2
2
 
3
- ## A module for layerbase database tool
3
+ [![npm version](https://img.shields.io/npm/v/layerbase.svg)](https://www.npmjs.com/package/layerbase)
4
+ [![license](https://img.shields.io/npm/l/layerbase.svg)](https://www.npmjs.com/package/layerbase)
4
5
 
5
- ## Status:
6
+ The Layerbase cloud CLI: connect to your managed cloud databases with their
7
+ native clients, drop into local [spindb](https://github.com/robertjbass/spindb),
8
+ and never paste a connection string into your shell history.
6
9
 
7
- ```json
8
- {
9
- "published": false
10
- }
10
+ `layerbase` is the bridge between **spindb** (the open-source local database
11
+ manager) and your **Layerbase cloud** account. Think `flyctl` / `heroku` /
12
+ `neonctl`, but it also wraps spindb for local work.
13
+
14
+ ## Install
15
+
16
+ ```bash
17
+ npm i -g layerbase
18
+ # or
19
+ pnpm add -g layerbase
20
+ # or
21
+ bun add -g layerbase
22
+ ```
23
+
24
+ This installs two commands, `layerbase` and a shorter `lbase`. For a two-letter
25
+ `lb`, run `layerbase alias` (it only claims `lb` if nothing else owns it).
26
+
27
+ ## Quick start
28
+
29
+ ```bash
30
+ layerbase # open the interactive menu
31
+ layerbase login # sign in through your browser
32
+ layerbase ls # list your cloud databases
33
+ layerbase psql my-db # connect with the right client, no password typed
11
34
  ```
35
+
36
+ ## Commands
37
+
38
+ | Command | Description |
39
+ | --- | --- |
40
+ | `layerbase` | Interactive menu: a hub to sign in, list, connect, and run spindb. |
41
+ | `layerbase login` | Sign in via the browser; stores a token in `~/.layerbase-cli`. |
42
+ | `layerbase logout` | Remove the stored credentials. |
43
+ | `layerbase whoami` | Show the signed-in account and token expiry (`--json`). |
44
+ | `layerbase ls` | List your cloud databases (`--json` for scripting). |
45
+ | `layerbase connect <db>` | Connect with the engine's native client. |
46
+ | `layerbase psql <db>` | Connect to a Postgres-family database. |
47
+ | `layerbase redis-cli <db>` | Connect to a Redis / Valkey database. |
48
+ | `layerbase mysql <db>` | Connect to a MySQL / MariaDB database. |
49
+ | `layerbase connection-string <db>` | Print the connection string (reveals the password). |
50
+ | `layerbase spindb [args...]` | Run the local spindb CLI (passes args through). |
51
+ | `layerbase alias` | Set up the short `lb` command (only if it is free). |
52
+
53
+ `<db>` accepts a cloud database id or its name. Add `--print` to `connect` to
54
+ show the connection details instead of launching a client.
55
+
56
+ ## Interactive menu
57
+
58
+ Run `layerbase` with no command for an arrow-key menu. It is a small hub: each
59
+ action runs, then the menu returns, so you can sign in, list databases, drop
60
+ into spindb, and keep going.
61
+
62
+ ```
63
+ ◆ Layerbase cloud + local databases
64
+
65
+ Signed in as you@example.com
66
+
67
+ ❯ List cloud databases
68
+ Connect to a database
69
+ Run spindb local databases
70
+ Log out
71
+ Quit
72
+
73
+ Up/Down to move · Enter to select · q to quit
74
+ ```
75
+
76
+ The menu is sugar over the commands above, so everything stays scriptable.
77
+
78
+ ## The spindb bridge
79
+
80
+ [spindb](https://github.com/robertjbass/spindb) manages local database
81
+ containers; `layerbase` adds the cloud account layer around it.
82
+
83
+ ```bash
84
+ layerbase spindb # open spindb's own menu
85
+ layerbase spindb create postgres # run any spindb command locally
86
+ ```
87
+
88
+ spindb is found on your `PATH`, or run through `npx` / `pnpx` / `bunx` if it is
89
+ not installed. Local spindb commands need no login.
90
+
91
+ ## Connecting without a connection string
92
+
93
+ Passing `psql "postgresql://user:SECRET@host/db"` leaks the password into your
94
+ shell history, into `ps` while the client runs, and into terminal scrollback.
95
+ `layerbase` resolves the database over TLS and hands the credential to the
96
+ client through an environment variable or a transient `0600` file that is
97
+ deleted on exit. The password is never an argv value.
98
+
99
+ | Engine | How the password is passed |
100
+ | --- | --- |
101
+ | Postgres family | `PGPASSFILE` (temp `0600` file), deleted on exit |
102
+ | MySQL / MariaDB | `--defaults-extra-file` (temp `0600` file), deleted on exit |
103
+ | Redis / Valkey | `REDISCLI_AUTH` environment variable |
104
+ | Other engines | `layerbase connection-string` / `--print` |
105
+
106
+ Connecting requires the engine's native client (`psql`, `mysql`, `redis-cli`)
107
+ on your `PATH`.
108
+
109
+ ## Authentication
110
+
111
+ `layerbase login` opens your browser, you sign in with GitHub or Google, and a
112
+ 30-day token is returned to a loopback server the CLI runs on `127.0.0.1`. A
113
+ state nonce ties the response to your login, and the token is only ever
114
+ delivered to a loopback address. It is stored at
115
+ `~/.layerbase-cli/credentials.json` (mode `0600`). This mirrors how the
116
+ Layerbase desktop app signs in. Run `layerbase logout` to remove it.
117
+
118
+ ## The `lb` shortcut
119
+
120
+ The CLI installs as `layerbase` and `lbase`. For a two-letter `lb`, run
121
+ `layerbase alias` (or pick it from the menu). It creates `lb` next to the
122
+ `layerbase` binary, but only when `lb` is not already taken on your system (for
123
+ example, Debian's `live-build` ships an `lb`). If it is taken, the CLI leaves it
124
+ alone and suggests a shell alias instead.
125
+
126
+ ## Configuration
127
+
128
+ | Variable | Purpose |
129
+ | --- | --- |
130
+ | `LAYERBASE_API_URL` | Override the Layerbase API base (default `https://layerbase.com`). |
131
+
132
+ ## Requirements
133
+
134
+ - Node.js 20 or newer.
135
+ - For `connect` / `psql` / `redis-cli` / `mysql`: the matching native client on
136
+ your `PATH`.
137
+
138
+ ## License
139
+
140
+ ISC, Layerbase, LLC.
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env node
2
+ // No build step: tsx transpiles the TypeScript/JSX entry at runtime.
3
+ import { tsImport } from 'tsx/esm/api'
4
+
5
+ await tsImport('../src/cli.tsx', import.meta.url)
package/package.json CHANGED
@@ -1,19 +1,64 @@
1
1
  {
2
2
  "name": "layerbase",
3
- "version": "0.0.3",
4
- "description": "Layerbase CLI",
3
+ "version": "0.1.1",
4
+ "description": "Layerbase cloud CLI: connect to your managed databases without leaking the connection string into shell history.",
5
5
  "type": "module",
6
6
  "bin": {
7
- "layerbase": "./bin/main.js"
7
+ "layerbase": "bin/layerbase.mjs",
8
+ "lbase": "bin/layerbase.mjs"
8
9
  },
9
10
  "files": [
10
- "bin"
11
+ "bin",
12
+ "src"
13
+ ],
14
+ "engines": {
15
+ "node": ">=20"
16
+ },
17
+ "scripts": {
18
+ "dev": "tsx src/cli.tsx",
19
+ "start": "node bin/layerbase.mjs",
20
+ "format": "prettier --write .",
21
+ "lint": "eslint .",
22
+ "check:types": "tsc --noEmit",
23
+ "check": "tsc --noEmit && eslint ."
24
+ },
25
+ "dependencies": {
26
+ "ink": "^7.1.0",
27
+ "ink-spinner": "^5.0.0",
28
+ "meow": "^14.1.0",
29
+ "react": "^19.2.0",
30
+ "tsx": "^4.22.4"
31
+ },
32
+ "devDependencies": {
33
+ "@eslint/js": "^9.18.0",
34
+ "@types/node": "^22.10.2",
35
+ "@types/react": "^19.2.0",
36
+ "eslint": "^9.18.0",
37
+ "prettier": "^3.4.2",
38
+ "typescript": "^5.7.2",
39
+ "typescript-eslint": "^8.18.0"
40
+ },
41
+ "keywords": [
42
+ "layerbase",
43
+ "database",
44
+ "cli",
45
+ "postgres",
46
+ "mysql",
47
+ "mariadb",
48
+ "redis",
49
+ "valkey",
50
+ "cloud"
11
51
  ],
12
- "keywords": [],
13
52
  "author": "Bob Bass",
14
53
  "license": "ISC",
54
+ "repository": {
55
+ "type": "git",
56
+ "url": "git+https://github.com/Layerbase-LLC/layerbase-cli.git"
57
+ },
58
+ "homepage": "https://layerbase.com",
15
59
  "publishConfig": {
16
- "access": "public"
60
+ "access": "public",
61
+ "provenance": true
17
62
  },
18
63
  "packageManager": "pnpm@10.23.0"
19
64
  }
package/src/cli.tsx ADDED
@@ -0,0 +1,69 @@
1
+ import meow from 'meow'
2
+ import { render } from 'ink'
3
+ import { App } from './ui/app'
4
+ import { runExec } from './commands/connect'
5
+ import { runInteractive } from './commands/interactive'
6
+ import { runSpindb } from './lib/run-spindb'
7
+
8
+ const cli = meow(
9
+ `
10
+ Usage
11
+ $ layerbase <command> [options]
12
+
13
+ Commands
14
+ login Sign in via your browser; saves a token to ~/.layerbase-cli
15
+ logout Remove the stored credentials
16
+ whoami Show the signed-in account (--json to script it)
17
+ ls List your cloud databases
18
+ connect <db> Connect with the right client for the engine
19
+ psql <db> Connect to a Postgres-family database
20
+ redis-cli <db> Connect to a Redis/Valkey database
21
+ mysql <db> Connect to a MySQL/MariaDB database
22
+ connection-string <db> Print the connection string (reveals the password)
23
+ spindb [args...] Run the local spindb CLI (passes args through)
24
+ alias Set up the short lb command (only if it is free)
25
+
26
+ Run with no command for an interactive menu. Also installed as lbase.
27
+
28
+ Options
29
+ --print With connect: show connection info, do not exec
30
+ --json With ls: print JSON instead of a table
31
+ --api-url <url> Cloud API base (env: LAYERBASE_API_URL)
32
+
33
+ Examples
34
+ $ layerbase # interactive menu
35
+ $ layerbase login
36
+ $ layerbase ls
37
+ $ layerbase psql my-db
38
+ $ layerbase spindb create postgres
39
+ `,
40
+ {
41
+ importMeta: import.meta,
42
+ flags: {
43
+ print: { type: 'boolean', default: false },
44
+ json: { type: 'boolean', default: false },
45
+ apiUrl: { type: 'string' },
46
+ },
47
+ },
48
+ )
49
+
50
+ const EXEC_COMMANDS = new Set(['connect', 'psql', 'redis-cli', 'mysql'])
51
+
52
+ const [command = '', ...rest] = cli.input
53
+
54
+ if (command === 'help') {
55
+ cli.showHelp(0)
56
+ } else if (!command) {
57
+ // No command: interactive menu on a TTY, help otherwise (pipes, CI).
58
+ if (process.stdin.isTTY) {
59
+ await runInteractive(cli.flags)
60
+ } else {
61
+ cli.showHelp(0)
62
+ }
63
+ } else if (command === 'spindb') {
64
+ process.exit(await runSpindb(rest))
65
+ } else if (EXEC_COMMANDS.has(command)) {
66
+ await runExec({ command, args: rest, flags: cli.flags })
67
+ } else {
68
+ render(<App command={command} args={rest} flags={cli.flags} />)
69
+ }
@@ -0,0 +1,28 @@
1
+ import { useEffect, useState } from 'react'
2
+ import { Text, useApp } from 'ink'
3
+ import { setupLb } from '../lib/alias'
4
+
5
+ type Result = { ok: boolean; text: string }
6
+
7
+ // Sets up the short `lb` command, but only when it is free on this system.
8
+ export function Alias() {
9
+ const { exit } = useApp()
10
+ const [result, setResult] = useState<Result | null>(null)
11
+
12
+ useEffect(() => {
13
+ const outcome = setupLb()
14
+ if (outcome.ok) {
15
+ setResult({ ok: true, text: 'The `lb` shortcut is ready. Try `lb`.' })
16
+ } else {
17
+ process.exitCode = 1
18
+ setResult({ ok: false, text: outcome.reason })
19
+ }
20
+ }, [])
21
+
22
+ useEffect(() => {
23
+ if (result) exit()
24
+ }, [result, exit])
25
+
26
+ if (!result) return null
27
+ return <Text color={result.ok ? 'green' : 'yellow'}>{result.text}</Text>
28
+ }
@@ -0,0 +1,66 @@
1
+ import { render } from 'ink'
2
+ import { Connecting } from '../ui/connecting'
3
+ import { getConnectionInfo } from '../lib/cloud-api'
4
+ import { buildLaunchPlan } from '../lib/engines'
5
+ import { runClient } from '../lib/launch'
6
+ import { printConnectionInfo } from '../lib/format'
7
+ import type { CommandFlags } from '../ui/app'
8
+
9
+ type ExecOptions = {
10
+ command: string
11
+ args: string[]
12
+ flags: CommandFlags
13
+ }
14
+
15
+ // Resolve a database and hand the TTY to its native client. Returns the client's
16
+ // exit code (or 1 on a resolve/launch error) WITHOUT exiting the process, so it
17
+ // is reusable from both the CLI path and the interactive menu. Ink renders only
18
+ // a transient spinner during the cloud lookup, then unmounts before the client
19
+ // takes over the terminal.
20
+ export async function connectToDatabase(options: {
21
+ dbRef: string
22
+ command: string
23
+ print?: boolean
24
+ }): Promise<number> {
25
+ const { dbRef, command, print } = options
26
+
27
+ const spinner = render(<Connecting label={`Resolving ${dbRef}...`} />)
28
+ let info
29
+ try {
30
+ info = await getConnectionInfo(dbRef)
31
+ } catch (error) {
32
+ spinner.unmount()
33
+ process.stderr.write(`${(error as Error).message}\n`)
34
+ return 1
35
+ }
36
+ spinner.unmount()
37
+
38
+ if (print) {
39
+ printConnectionInfo(info)
40
+ return 0
41
+ }
42
+
43
+ let plan
44
+ try {
45
+ plan = buildLaunchPlan({ info, command })
46
+ } catch (error) {
47
+ process.stderr.write(`${(error as Error).message}\n`)
48
+ return 1
49
+ }
50
+
51
+ return runClient(plan)
52
+ }
53
+
54
+ // CLI entrypoint for connect/psql/redis-cli/mysql: resolve + launch, then exit.
55
+ export async function runExec(options: ExecOptions): Promise<void> {
56
+ const { command, flags } = options
57
+ const dbRef = options.args[0]
58
+
59
+ if (!dbRef) {
60
+ process.stderr.write(`Usage: layerbase ${command} <db>\n`)
61
+ process.exit(1)
62
+ }
63
+
64
+ const code = await connectToDatabase({ dbRef, command, print: flags.print })
65
+ process.exit(code)
66
+ }
@@ -0,0 +1,49 @@
1
+ import { useEffect, useState } from 'react'
2
+ import { Text, useApp } from 'ink'
3
+ import { getConnectionInfo } from '../lib/cloud-api'
4
+ import { buildConnectionString } from '../lib/format'
5
+
6
+ type State =
7
+ | { kind: 'loading' }
8
+ | { kind: 'error'; message: string }
9
+ | { kind: 'done' }
10
+
11
+ // Opt-in escape hatch: prints the full connection string (with password) to
12
+ // stdout for piping into an app. The secure path is `layerbase connect`.
13
+ export function ConnectionString({ dbRef }: { dbRef: string | undefined }) {
14
+ const { exit } = useApp()
15
+ const [state, setState] = useState<State>({ kind: 'loading' })
16
+
17
+ useEffect(() => {
18
+ async function fetchAndPrintConnectionString() {
19
+ if (!dbRef) {
20
+ setState({
21
+ kind: 'error',
22
+ message: 'Usage: layerbase connection-string <db>',
23
+ })
24
+ process.exitCode = 1
25
+ return
26
+ }
27
+ try {
28
+ const info = await getConnectionInfo(dbRef)
29
+ process.stdout.write(`${buildConnectionString(info)}\n`)
30
+ setState({ kind: 'done' })
31
+ } catch (error) {
32
+ setState({ kind: 'error', message: (error as Error).message })
33
+ process.exitCode = 1
34
+ }
35
+ }
36
+ fetchAndPrintConnectionString()
37
+ }, [dbRef])
38
+
39
+ useEffect(() => {
40
+ if (state.kind !== 'loading') {
41
+ exit()
42
+ }
43
+ }, [state, exit])
44
+
45
+ if (state.kind === 'error') {
46
+ return <Text color="red">{state.message}</Text>
47
+ }
48
+ return null
49
+ }
@@ -0,0 +1,168 @@
1
+ import { render, Box, Text } from 'ink'
2
+ import { Menu } from '../ui/menu'
3
+ import type { MenuItem } from '../ui/menu'
4
+ import { Header } from '../ui/brand'
5
+ import { Connecting } from '../ui/connecting'
6
+ import { PressEnter } from '../ui/press-enter'
7
+ import { loadCredentials } from '../lib/config'
8
+ import type { StoredCredentials } from '../lib/config'
9
+ import { decodeTokenClaims } from '../lib/token'
10
+ import { listDatabases } from '../lib/cloud-api'
11
+ import type { CloudDatabase } from '../lib/cloud-api'
12
+ import { runSpindb } from '../lib/run-spindb'
13
+ import { connectToDatabase } from './connect'
14
+ import { lbStatus } from '../lib/alias'
15
+ import { App } from '../ui/app'
16
+ import type { CommandFlags } from '../ui/app'
17
+
18
+ const BACK = '__back__'
19
+
20
+ function clearScreen(): void {
21
+ // Clear the visible screen and home the cursor (scrollback is preserved).
22
+ process.stdout.write('')
23
+ }
24
+
25
+ function accountLine(creds: StoredCredentials | null): {
26
+ text: string
27
+ loggedIn: boolean
28
+ } {
29
+ if (!creds) return { text: 'Not signed in', loggedIn: false }
30
+ const email = decodeTokenClaims(creds.token)?.email
31
+ return { text: email ? `Signed in as ${email}` : 'Signed in', loggedIn: true }
32
+ }
33
+
34
+ function buildItems(loggedIn: boolean, lbAvailable: boolean): MenuItem[] {
35
+ const items: MenuItem[] = []
36
+ if (loggedIn) {
37
+ items.push({ label: 'List cloud databases', value: 'ls' })
38
+ items.push({ label: 'Connect to a database', value: 'connect' })
39
+ } else {
40
+ items.push({ label: 'Log in', value: 'login', hint: 'browser sign-in' })
41
+ }
42
+ items.push({ label: 'Run spindb', value: 'spindb', hint: 'local databases' })
43
+ if (loggedIn) items.push({ label: 'Log out', value: 'logout' })
44
+ if (lbAvailable) {
45
+ items.push({ label: 'Enable the lb shortcut', value: 'alias' })
46
+ }
47
+ items.push({ label: 'Quit', value: 'quit' })
48
+ return items
49
+ }
50
+
51
+ function pick(creds: StoredCredentials | null): Promise<string> {
52
+ const loggedIn = Boolean(creds)
53
+ const lbAvailable = lbStatus().state === 'available'
54
+ const items = buildItems(loggedIn, lbAvailable)
55
+ const account = accountLine(creds)
56
+
57
+ return new Promise<string>((resolve) => {
58
+ const app = render(
59
+ <Box flexDirection="column" paddingX={1} paddingY={1}>
60
+ <Header subtitle="cloud + local databases" />
61
+ <Box marginBottom={1}>
62
+ <Text
63
+ color={account.loggedIn ? 'green' : undefined}
64
+ dimColor={!account.loggedIn}
65
+ >
66
+ {account.text}
67
+ </Text>
68
+ </Box>
69
+ <Menu
70
+ items={items}
71
+ onSelect={(value) => {
72
+ app.unmount()
73
+ resolve(value)
74
+ }}
75
+ />
76
+ </Box>,
77
+ )
78
+ })
79
+ }
80
+
81
+ function pickDatabase(databases: CloudDatabase[]): Promise<string | null> {
82
+ const items: MenuItem[] = databases.map((db) => ({
83
+ label: db.name,
84
+ value: db.id,
85
+ hint: `${db.engine} · ${db.status}`,
86
+ }))
87
+ items.push({ label: 'Back', value: BACK })
88
+
89
+ return new Promise<string | null>((resolve) => {
90
+ const app = render(
91
+ <Box flexDirection="column" paddingX={1} paddingY={1}>
92
+ <Text bold>Pick a database to connect to</Text>
93
+ <Box marginTop={1}>
94
+ <Menu
95
+ items={items}
96
+ onSelect={(value) => {
97
+ app.unmount()
98
+ resolve(value === BACK ? null : value)
99
+ }}
100
+ />
101
+ </Box>
102
+ </Box>,
103
+ )
104
+ })
105
+ }
106
+
107
+ // Menu action: list the user's databases, let them pick one, and connect with
108
+ // the right client. Returns to the hub when the client exits (or on Back/error).
109
+ async function runConnectFlow(): Promise<void> {
110
+ const spinner = render(<Connecting label="Loading your databases..." />)
111
+ let databases: CloudDatabase[]
112
+ try {
113
+ databases = await listDatabases()
114
+ } catch (error) {
115
+ spinner.unmount()
116
+ process.stderr.write(`${(error as Error).message}\n`)
117
+ return
118
+ }
119
+ spinner.unmount()
120
+
121
+ if (databases.length === 0) {
122
+ process.stdout.write(
123
+ 'No databases yet. Create one at https://layerbase.com.\n',
124
+ )
125
+ return
126
+ }
127
+
128
+ const dbRef = await pickDatabase(databases)
129
+ if (!dbRef) return
130
+
131
+ await connectToDatabase({ dbRef, command: 'connect' })
132
+ }
133
+
134
+ async function waitForEnter(): Promise<void> {
135
+ const instance = render(<PressEnter />)
136
+ await instance.waitUntilExit()
137
+ }
138
+
139
+ // The no-command experience: a small hub. Each action runs on a clean screen,
140
+ // then waits for Enter and returns to the menu, so you can sign in, then list,
141
+ // then connect, ... Cloud actions depend on auth; spindb is always offered.
142
+ export async function runInteractive(flags: CommandFlags): Promise<void> {
143
+ for (;;) {
144
+ clearScreen()
145
+ const creds = await loadCredentials()
146
+ const choice = await pick(creds)
147
+
148
+ if (choice === 'quit') {
149
+ clearScreen()
150
+ process.exitCode = 0
151
+ return
152
+ }
153
+
154
+ clearScreen()
155
+ if (choice === 'spindb') {
156
+ await runSpindb([])
157
+ } else if (choice === 'connect') {
158
+ await runConnectFlow()
159
+ } else {
160
+ // login / logout / ls / alias run through the same Ink dispatcher as
161
+ // typed commands; wait for the action to finish.
162
+ const instance = render(<App command={choice} args={[]} flags={flags} />)
163
+ await instance.waitUntilExit()
164
+ }
165
+
166
+ await waitForEnter()
167
+ }
168
+ }