@liaisonio/cli 0.1.1 → 0.2.1

package/README.md

@@ -3,11 +3,14 @@
 Official command-line interface for [liaison.cloud](https://liaison.cloud), designed
 to be **scripted and agent-friendly**.
 
-- JSON output by default — ready for piping into `jq` or parsing by LLM agents
+- **One-shot bootstrap** — `liaison quickstart` creates a connector + application + public entry in a single call
+- **5 Agent Skills** — drop-in Skill files for AI agents (Claude/Cursor/etc.), installable via `npx skills add liaisonio/cli`
+- JSON output by default — pipe into `jq` or parse from any LLM agent
 - `--output table` for humans, `--output yaml` when you prefer it
 - Credentials from env var (`LIAISON_TOKEN`), config file, or explicit `--token` flag
+- Browser-based PAT login (or `--no-browser` for headless / SSH)
 - Every command has `-h` / `--help` with examples
-- Non-interactive by default: destructive operations require `--yes`
+- Non-interactive by default — destructive operations require `--yes`
 
 ## Install
 
@@ -62,30 +65,88 @@ liaison version
 
 ## Authenticate
 
-The CLI accepts a JWT bearer token issued by liaison.cloud. For now the slider-captcha
-login flow used by the web UI is not supported headlessly — you need to obtain the
-token out of band:
+The CLI uses long-lived **Personal Access Tokens** (PATs) — `liaison_pat_xxx...`
+issued by the Liaison dashboard. Three ways to provide one:
 
-1. Log in to [liaison.cloud](https://liaison.cloud) in your browser.
-2. Open DevTools → Application → Local Storage → copy the `authorization` value.
-3. Persist it:
+```bash
+# 1) Browser flow (recommended for humans)
+liaison login
+# Opens https://liaison.cloud/dashboard/cli-auth in your default browser,
+# you click "Authorize", a fresh PAT is minted and persisted to ~/.liaison/config.yaml.
+
+# 2) SSH / headless / no browser
+liaison login --no-browser
+# Prints the URL — open it on any device that has a browser, click Authorize,
+# the CLI receives the token via a localhost callback.
+
+# 3) Already have a token (CI, agent secrets store)
+LIAISON_TOKEN=liaison_pat_a1b2c3... liaison whoami
+# Or: liaison login --token liaison_pat_a1b2c3...
+```
+
+Precedence (highest wins): `--token` flag → `LIAISON_TOKEN` env → `~/.liaison/config.yaml` → no token.
+
+Tokens can be revoked any time at **liaison.cloud → Settings → API Tokens**, or by running:
+
+```bash
+liaison logout
+```
+
+## Quick Start
+
+The fastest way to expose a local service:
+
+```bash
+# 1) authenticate once
+liaison login
+
+# 2) bootstrap a connector + register your service + expose it publicly
+liaison quickstart --name mybox \
+  --app-name web --app-ip 127.0.0.1 --app-port 8080 --app-protocol http \
+  --expose --wait-online 2m
+
+# The output JSON includes:
+#   - install_command  → run this on your target host (curl|bash one-liner)
+#   - entry.port       → public TCP port (or entry.domain for http)
+#   - online_achieved  → whether the connector successfully connected
+```
+
+`liaison quickstart` is a single command that:
+
+1. Creates the connector (and returns the install command for the host)
+2. Optionally runs the install script locally (`--install`, requires sudo)
+3. Optionally polls for the connector to come online (`--wait-online <duration>`)
+4. Optionally registers a backend application (`--app-*` flags)
+5. Optionally exposes it via a public entry (`--expose`)
 
-   ```bash
-   liaison login --token eyJhbGciOi...
-   ```
+See `liaison quickstart --help` for the full flag list.
 
-   This writes `~/.liaison/config.yaml` (mode 0600) and verifies the token against
-   `/api/v1/iam/profile_json`.
+## Agent Skills
 
-Alternatively, skip the config file entirely and pass the token per-invocation:
+This CLI ships **5 [Skill files](./skills/)** so AI agents (Claude, Cursor, Continue, etc.)
+know how to use it without a learning curve. Each skill is a self-contained Markdown
+spec with frontmatter — installable with one command:
 
 ```bash
-LIAISON_TOKEN=eyJhbGciOi... liaison edge list
-# or
-liaison --token eyJhbGciOi... edge list
+# Install all liaison skills into the agent's skills directory
+npx skills add liaisonio/cli -y -g
 ```
 
-Precedence (highest wins): `--token` flag → `LIAISON_TOKEN` env → config file → built-in default.
+| Skill | Purpose |
+|-------|---------|
+| `liaison-shared` | Auth, install, token precedence, error handling, output format (auto-loaded by other skills) |
+| `liaison-quickstart` | One-shot bootstrap: connector + application + entry in a single call |
+| `liaison-connector` | Connector lifecycle: create / list / inspect / enable+disable / delete |
+| `liaison-application` | Backend service metadata: register / list / update / delete |
+| `liaison-entry` | Public exposure: HTTP domains, TCP ports, enable+disable, delete |
+
+After installing the skills, point your agent at `liaison.cloud` and ask it
+things like:
+
+- "Set up a public SSH endpoint for my home server"
+- "List all my connectors and tell me which ones are offline"
+- "Disable connector 100017 — I'm doing maintenance"
+- "Expose the local Postgres on 5432 via Liaison"
 
 ## Usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liaisonio/cli",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Liaison Cloud CLI — manage connectors, entries, and applications from the command line",
   "keywords": [
     "liaison",

package/scripts/install.js

@@ -11,21 +11,35 @@
 //   - The user is on an unsupported platform (we exit 0 + warn, NOT fail,
 //     so npm install doesn't break for transitive deps)
 //
+// Honours HTTPS_PROXY / HTTP_PROXY env vars for users behind corporate proxies
+// (Node's built-in https.get does NOT honour these out of the box — we handle
+// it manually via a CONNECT tunnel). Retries once on transient network errors.
+//
 // Network failures DO fail the install — silently shipping a broken package
 // is worse than a clear error the user can retry.
 
 'use strict';
 
 const https = require('https');
+const http = require('http');
+const net = require('net');
+const tls = require('tls');
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { URL } = require('url');
 
 const pkg = require('../package.json');
 const VERSION = `v${pkg.version}`;
 const REPO = 'liaisonio/cli';
 const RELEASE_BASE = `https://github.com/${REPO}/releases/download/${VERSION}`;
 
+// How long to wait for a single HTTP round-trip before giving up.
+const SOCKET_TIMEOUT_MS = 30_000;
+// How many times to retry a download after a transient error. Retries are
+// linear-backoff with 2s then 5s gaps.
+const RETRY_DELAYS_MS = [2000, 5000];
+
 // process.platform-process.arch → release asset GOOS-GOARCH suffix.
 const PLATFORMS = {
   'darwin-arm64': { os: 'darwin', arch: 'arm64', ext: '' },
@@ -73,74 +87,186 @@ const destPath = path.join(vendorDir, `liaison${platform.ext}`);
 
 fs.mkdirSync(vendorDir, { recursive: true });
 
-// Followed-redirect HTTP GET that streams to a file.
-function downloadToFile(targetUrl, outPath) {
+// ─── proxy support ──────────────────────────────────────────────────────────
+
+// getProxy reads HTTPS_PROXY / HTTP_PROXY / https_proxy / http_proxy, in the
+// order npm / curl do. Returns a parsed URL or null.
+function getProxy() {
+  const raw =
+    process.env.HTTPS_PROXY ||
+    process.env.https_proxy ||
+    process.env.HTTP_PROXY ||
+    process.env.http_proxy;
+  if (!raw) return null;
+  try {
+    return new URL(raw);
+  } catch {
+    warn(`ignoring invalid proxy URL: ${raw}`);
+    return null;
+  }
+}
+
+// tunnelThroughProxy opens a TCP connection to the proxy, issues an HTTP
+// CONNECT to the target, and upgrades the socket to TLS. Returns a Promise
+// resolving to an established TLSSocket that can be handed to https.request
+// as `createConnection`. Zero external dependencies.
+function tunnelThroughProxy(proxy, targetHost, targetPort) {
   return new Promise((resolve, reject) => {
-    const file = fs.createWriteStream(outPath);
-    function get(u, depth) {
-      if (depth > 5) {
-        reject(new Error(`too many redirects fetching ${targetUrl}`));
+    const proxyPort = proxy.port || (proxy.protocol === 'https:' ? 443 : 80);
+    const authHeader = proxy.username
+      ? `Proxy-Authorization: Basic ${Buffer.from(
+          `${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password || '')}`,
+        ).toString('base64')}\r\n`
+      : '';
+
+    const proxySocket = net.connect(proxyPort, proxy.hostname, () => {
+      proxySocket.write(
+        `CONNECT ${targetHost}:${targetPort} HTTP/1.1\r\n` +
+          `Host: ${targetHost}:${targetPort}\r\n` +
+          authHeader +
+          `\r\n`,
+      );
+    });
+
+    let buf = Buffer.alloc(0);
+    const onData = (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      const end = buf.indexOf('\r\n\r\n');
+      if (end === -1) return;
+      const head = buf.slice(0, end).toString('utf8');
+      const status = head.split(' ')[1];
+      proxySocket.removeListener('data', onData);
+      if (status !== '200') {
+        reject(new Error(`proxy CONNECT failed: ${head.split('\r\n')[0]}`));
+        proxySocket.end();
         return;
       }
-      https
-        .get(u, { headers: { 'User-Agent': 'liaison-cli-installer' } }, (res) => {
-          if (
-            res.statusCode &&
-            res.statusCode >= 300 &&
-            res.statusCode < 400 &&
-            res.headers.location
-          ) {
-            res.resume();
-            get(res.headers.location, depth + 1);
-            return;
-          }
-          if (res.statusCode !== 200) {
-            reject(new Error(`HTTP ${res.statusCode} for ${u}`));
-            res.resume();
-            return;
-          }
-          res.pipe(file);
-          file.on('finish', () => file.close(() => resolve()));
-          file.on('error', reject);
-        })
-        .on('error', reject);
-    }
-    get(targetUrl, 0);
+      // Upgrade to TLS — the CONNECT tunnel is now a raw TCP pipe to target.
+      const tlsSocket = tls.connect({
+        socket: proxySocket,
+        servername: targetHost,
+      });
+      tlsSocket.once('secureConnect', () => resolve(tlsSocket));
+      tlsSocket.once('error', reject);
+    };
+    proxySocket.on('data', onData);
+    proxySocket.once('error', reject);
   });
 }
 
-function downloadToString(targetUrl) {
+// httpsGetRaw makes a single HTTPS GET request. If an HTTPS_PROXY is set, it
+// tunnels through it via CONNECT; otherwise it uses stock https.request.
+// Returns a Promise<IncomingMessage>. Caller is responsible for consuming or
+// discarding the body.
+function httpsGetRaw(targetUrl) {
   return new Promise((resolve, reject) => {
-    function get(u, depth) {
-      if (depth > 5) {
-        reject(new Error(`too many redirects fetching ${targetUrl}`));
-        return;
+    const u = new URL(targetUrl);
+    const proxy = getProxy();
+
+    const reqOptions = {
+      host: u.hostname,
+      port: u.port || 443,
+      path: u.pathname + u.search,
+      method: 'GET',
+      headers: {
+        'User-Agent': 'liaison-cli-installer',
+        Host: u.host,
+      },
+      timeout: SOCKET_TIMEOUT_MS,
+    };
+
+    const runRequest = (agentSocket) => {
+      if (agentSocket) {
+        reqOptions.createConnection = () => agentSocket;
       }
-      https
-        .get(u, { headers: { 'User-Agent': 'liaison-cli-installer' } }, (res) => {
-          if (
-            res.statusCode &&
-            res.statusCode >= 300 &&
-            res.statusCode < 400 &&
-            res.headers.location
-          ) {
-            res.resume();
-            get(res.headers.location, depth + 1);
-            return;
-          }
-          if (res.statusCode !== 200) {
-            reject(new Error(`HTTP ${res.statusCode} for ${u}`));
-            res.resume();
-            return;
-          }
-          let body = '';
-          res.setEncoding('utf8');
-          res.on('data', (chunk) => (body += chunk));
-          res.on('end', () => resolve(body));
-        })
-        .on('error', reject);
+      const req = https.request(reqOptions, resolve);
+      req.on('error', reject);
+      req.on('timeout', () => {
+        req.destroy(new Error(`timeout after ${SOCKET_TIMEOUT_MS}ms`));
+      });
+      req.end();
+    };
+
+    if (proxy) {
+      tunnelThroughProxy(proxy, u.hostname, u.port || 443)
+        .then(runRequest)
+        .catch(reject);
+    } else {
+      runRequest(null);
     }
-    get(targetUrl, 0);
+  });
+}
+
+// Follow HTTP redirects up to maxRedirects, returning the final IncomingMessage
+// that actually holds the body. Non-2xx status codes at the end of the chain
+// are returned as-is; caller decides whether to treat them as an error.
+async function httpsGet(targetUrl, maxRedirects = 5) {
+  let current = targetUrl;
+  for (let i = 0; i <= maxRedirects; i++) {
+    const res = await httpsGetRaw(current);
+    if (
+      res.statusCode >= 300 &&
+      res.statusCode < 400 &&
+      res.headers.location
+    ) {
+      res.resume();
+      current = res.headers.location;
+      continue;
+    }
+    return res;
+  }
+  throw new Error(`too many redirects fetching ${targetUrl}`);
+}
+
+// withRetry wraps an async function so it's tried a few times with backoff
+// on network errors. Does NOT retry on 4xx/5xx from the server — those are
+// deterministic and a retry will just hit the same error.
+async function withRetry(label, fn) {
+  let lastErr;
+  for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (attempt < RETRY_DELAYS_MS.length) {
+        const delay = RETRY_DELAYS_MS[attempt];
+        warn(`${label}: ${err.message}, retrying in ${delay}ms...`);
+        await new Promise((r) => setTimeout(r, delay));
+        continue;
+      }
+    }
+  }
+  throw lastErr;
+}
+
+function downloadToFile(targetUrl, outPath) {
+  return withRetry(`download ${path.basename(outPath)}`, async () => {
+    const res = await httpsGet(targetUrl);
+    if (res.statusCode !== 200) {
+      res.resume();
+      throw new Error(`HTTP ${res.statusCode} for ${targetUrl}`);
+    }
+    await new Promise((resolve, reject) => {
+      const file = fs.createWriteStream(outPath);
+      res.pipe(file);
+      file.on('finish', () => file.close(() => resolve()));
+      file.on('error', reject);
+      res.on('error', reject);
+    });
+  });
+}
+
+function downloadToString(targetUrl) {
+  return withRetry(`fetch ${path.basename(new URL(targetUrl).pathname)}`, async () => {
+    const res = await httpsGet(targetUrl);
+    if (res.statusCode !== 200) {
+      res.resume();
+      throw new Error(`HTTP ${res.statusCode} for ${targetUrl}`);
+    }
+    let body = '';
+    res.setEncoding('utf8');
+    for await (const chunk of res) body += chunk;
+    return body;
   });
 }
 
@@ -151,6 +277,11 @@ function sha256(filepath) {
 }
 
 async function main() {
+  const proxy = getProxy();
+  if (proxy) {
+    log(`using proxy ${proxy.protocol}//${proxy.hostname}:${proxy.port || ''}`);
+  }
+
   log(`fetching ${url}`);
   await downloadToFile(url, destPath);
   fs.chmodSync(destPath, 0o755);
@@ -174,6 +305,10 @@ async function main() {
   log(`installed ${filename} (sha256 ok)`);
 }
 
+// Suppress the unused `http` import warning — kept for future use if we
+// ever need HTTP-not-HTTPS downloads (CI staging).
+void http;
+
 main().catch((err) => {
-  die(`download failed: ${err.message}`);
+  die(`download failed: ${err.message}. You can retry with \`npm rebuild @liaisonio/cli\`, or set HTTPS_PROXY if you're behind a corporate proxy.`);
 });