@quxkit/quxcloud 0.1.0 → 0.2.0

package/README.md

@@ -4,9 +4,8 @@ Work on a QuxCloud project in your own editor.
 
 ```
 npx @quxkit/quxcloud login    # opens your browser; approve the code shown
-npx @quxkit/quxcloud link     # pick the project this folder is
-npx @quxkit/quxcloud pull     # bring it down
-npx @quxkit/quxcloud watch    # every save goes back
+quxcloud clone                # pick the project this folder is, and bring it down
+quxcloud watch                # every save goes back
 ```
 
 Nothing is typed into your shell. `login` prints a short code, opens QuxCloud
@@ -14,6 +13,35 @@ in your browser, and waits while you approve it there — so no key reaches your
 history, your scrollback, or a screen share. The terminal receives an ordinary
 workspace API key, listed under **API keys** and revocable there.
 
+## The scope is typed once
+
+`login` is the only command that carries `@quxkit/`, because it is the only one
+you run before anything is installed. It installs the rest of itself:
+
+| | |
+|---|---|
+| `~/.config/quxcloud/lib` | the CLI — copied, not downloaded again; it has no dependencies |
+| `~/.config/quxcloud/bin/quxcloud` | a three-line shim, put on your `PATH` with your say-so |
+
+Not `npm i -g`, which binds the command to whichever Node you happened to be on
+and needs `sudo` under a Homebrew prefix. If you decline the `PATH` line, the
+command prints it for you to add yourself. `quxcloud upgrade` (or
+`npx @quxkit/quxcloud@latest upgrade`) refreshes the copy;
+`rm -rf ~/.config/quxcloud` removes it, key and all.
+
+## The commands
+
+| | |
+|---|---|
+| `clone` | link this folder to a project and pull it — `--relink` to choose again |
+| `pull` | bring the project down |
+| `push` | send your edits back |
+| `watch` | push on every save |
+| `link` | point this folder at a different project |
+| `whoami` | who this terminal is signed in as |
+| `upgrade` | reinstall the `quxcloud` command |
+| `logout` | forget the key on this machine |
+
 ## What does not come down
 
 The `@quxkit` packages are licensed through your workspace and stay there, so
@@ -25,13 +53,16 @@ need to run the whole thing on your own machine.
 ## In CI
 
 `QUXCLOUD_KEY` and `QUXCLOUD_PROJECT` still work and take precedence, so the
-same CLI runs unattended without an interactive login.
+same CLI runs unattended without an interactive login. Keep using
+`npx @quxkit/quxcloud pull` there — a build agent has no shell profile to put
+anything on, and nothing to gain from a second copy on disk.
 
 ## Where things are kept
 
 | | |
 |---|---|
 | `~/.config/quxcloud/config.json` | the key, mode 0600, one per machine |
+| `~/.config/quxcloud/bin`, `lib` | the installed `quxcloud` command |
 | `./.quxcloud` | which project this folder is — no secrets, commit it or don't |
 
 The bridge is on the paid plans.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quxkit/quxcloud",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Work on a QuxCloud project in your own editor.",
   "license": "Apache-2.0",
   "type": "module",

package/src/api.mjs

@@ -8,14 +8,24 @@ export class ApiError extends Error {
 }
 
 export async function request(url, path, { method = 'GET', key, body } = {}) {
-  const res = await fetch(`${url}${path}`, {
+  const options = {
     method,
     headers: {
       ...(key ? { authorization: `Bearer ${key}` } : {}),
       ...(body ? { 'content-type': 'application/json' } : {}),
     },
     ...(body ? { body: JSON.stringify(body) } : {}),
-  });
+  };
+
+  let res;
+  try {
+    res = await fetch(`${url}${path}`, options);
+  } catch (cause) {
+    // Undici says "fetch failed" and puts the reason in `cause`. Unwrapped,
+    // it names neither the host nor what went wrong with it.
+    const why = cause?.cause?.code ?? cause?.cause?.message ?? cause?.message ?? 'unknown error';
+    throw new ApiError(`could not reach ${url} (${why}). Check the connection, or --url if this should be a different QuxCloud.`, 0);
+  }
   const text = await res.text();
   let json = {};
   try {

package/src/commands.mjs

@@ -12,6 +12,7 @@ import { basename, dirname, join, relative, sep } from 'node:path';
 
 import { request } from './api.mjs';
 import { clearConfig, configPath, DEFAULT_URL, readConfig, readLink, resolve, writeConfig, writeLink } from './config.mjs';
+import { installAndAnnounce } from './install.mjs';
 import { ask, bold, choose, cyan, dim, die, green, openBrowser, say, spinner } from './ui.mjs';
 
 const sha = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16);
@@ -56,7 +57,13 @@ export async function login(argv) {
     spin.stop();
     writeConfig({ ...readConfig(), url, key: result.json.key });
     say(`${green('Signed in.')} The key is in ${dim(configPath())} and listed under API keys, revocable there.`);
-    say(`Next: ${bold('quxcloud link')} in your project folder.`);
+
+    // The one command that has to carry the scope is this one. Leave a
+    // `quxcloud` behind so no other command does.
+    say('');
+    await installAndAnnounce();
+    say('');
+    say(`Next: ${bold('quxcloud clone')} in your project folder.`);
     return;
   }
 }
@@ -79,7 +86,7 @@ export async function whoami() {
 
 /* ------------------------------------------------------------------- link -- */
 
-export async function link() {
+export async function link({ announceNext = true } = {}) {
   const at = resolve({ needProject: false });
   if (at.error) die(at.error);
   const { json } = await request(at.url, '/api/cli/projects', { key: at.key });
@@ -97,7 +104,35 @@ export async function link() {
 
   writeLink({ project: picked.id, name: picked.name, workspace: picked.workspace });
   say(`\n${green('Linked')} this folder to ${bold(picked.name)}.`);
-  say(`Next: ${bold('quxcloud pull')}`);
+  if (announceNext) say(`Next: ${bold('quxcloud pull')}`);
+  return picked;
+}
+
+/* ------------------------------------------------------------------ clone -- */
+
+/**
+ * Link and pull, which is what the first minute in a folder always is.
+ *
+ * Nobody links without pulling. Keeping them apart made the docs four lines
+ * long and made the second line a step you could forget between the first and
+ * the third. Already linked, this just pulls; `--relink` picks again.
+ */
+export async function clone(argv = {}) {
+  const existing = readLink();
+  if (existing.project && !argv.flags?.has('relink')) {
+    say(`Already linked to ${bold(existing.name ?? existing.project)}. ${dim('--relink to choose another.')}`);
+  } else {
+    await link({ announceNext: false });
+  }
+  await pull();
+}
+
+/* ---------------------------------------------------------------- upgrade -- */
+
+/** Re-install the shim from this copy — `npx @quxkit/quxcloud@latest upgrade`. */
+export async function upgrade() {
+  const { version, lib } = await installAndAnnounce();
+  say(dim(`quxcloud ${version ?? '?'} in ${lib}`));
 }
 
 /* ------------------------------------------------------------------- sync -- */

package/src/config.mjs

@@ -5,6 +5,8 @@
 //   ~/.config/quxcloud/config.json   the key. One per machine, mode 0600, and
 //                                    NEVER in the project — a credential in a
 //                                    working tree is a credential in a commit.
+//                                    `bin/` and `lib/` beside it are the
+//                                    installed CLI — see install.mjs.
 //   ./.quxcloud                      which project this directory is. Belongs
 //                                    with the code, holds nothing secret, and
 //                                    is what makes `pull` work with no
@@ -41,6 +43,10 @@ export function clearConfig() {
 }
 
 export const configPath = () => CONFIG_FILE;
+// The same directory holds the installed copy of the CLI. One place per
+// machine for everything quxcloud keeps, and — unlike ~/.quxcloud — no
+// collision with the `.quxcloud` link file of a project cloned into $HOME.
+export const configDir = () => CONFIG_DIR;
 
 export function readLink(root = process.cwd()) {
   return readJson(join(root, LINK_FILE));

package/src/index.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 // quxcloud — work on a QuxCloud project in your own editor.
 //
-//   npx @quxkit/quxcloud login    sign in through the browser
-//   npx @quxkit/quxcloud link     point this folder at a project
-//   npx @quxkit/quxcloud pull     bring it down
-//   npx @quxkit/quxcloud watch    push every save
+//   npx @quxkit/quxcloud login    sign in through the browser, and install
+//                                 `quxcloud` so this is the last time the
+//                                 scope has to be typed
+//   quxcloud clone                link this folder to a project and pull it
+//   quxcloud watch                push every save
 //
 // npm rather than a downloadable binary, and the reason is Gatekeeper. An
 // unsigned Mac binary opens to "cannot be opened because the developer cannot
@@ -13,42 +14,66 @@
 // Anyone building a Next.js app already has Node, so `npx` is one command on
 // all three platforms, needs no download, and updates itself.
 
-import { link, login, logout, pull, push, watch, whoami } from './commands.mjs';
+import { clone, link, login, logout, pull, push, upgrade, watch, whoami } from './commands.mjs';
+import { onPath } from './install.mjs';
 import { bold, die, dim, say } from './ui.mjs';
 
 const COMMANDS = {
   login: { run: login, blurb: 'sign in through your browser' },
-  logout: { run: logout, blurb: 'forget the key on this machine' },
-  whoami: { run: whoami, blurb: 'who this terminal is signed in as' },
-  link: { run: link, blurb: 'point this folder at a project' },
+  clone: { run: clone, blurb: 'link this folder to a project and pull it' },
   pull: { run: pull, blurb: 'bring the project down' },
   push: { run: push, blurb: 'send your edits back' },
   watch: { run: watch, blurb: 'push on every save' },
+  link: { run: link, blurb: 'point this folder at a different project' },
+  whoami: { run: whoami, blurb: 'who this terminal is signed in as' },
+  upgrade: { run: upgrade, blurb: 'reinstall the `quxcloud` command' },
+  logout: { run: logout, blurb: 'forget the key on this machine' },
 };
 
+// Names people reach for that mean something already in the list. Cheaper to
+// accept than to answer with `unknown command`.
+const ALIASES = { setup: 'clone', start: 'clone', init: 'clone', install: 'upgrade', sync: 'push', status: 'whoami' };
+
 function usage() {
   say(`${bold('quxcloud')} — your editor, QuxCloud's runtime\n`);
   for (const [name, { blurb }] of Object.entries(COMMANDS)) {
     say(`  ${bold(name.padEnd(8))} ${blurb}`);
   }
-  say(`\n${dim('Start with')} ${bold('quxcloud login')}${dim(', then')} ${bold('quxcloud link')}${dim(' in your project folder.')}`);
+  // Only the first command carries the scope, so only the first command is
+  // shown with it.
+  say(`\n${dim('First time:')} ${bold('npx @quxkit/quxcloud login')}`);
+  say(`${dim('After that:')}  ${bold('quxcloud clone')} ${dim('in your project folder, then')} ${bold('quxcloud watch')}`);
+  if (!onPath()) say(`\n${dim('`quxcloud` is not on this PATH yet — `npx @quxkit/quxcloud login` (or `upgrade`) puts it there.')}`);
+}
+
+/** Flags this small do not need a parser library. */
+function parse(rest) {
+  const argv = { _: [], flags: new Set() };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--url') argv.url = rest[++i];
+    else if (arg.startsWith('--')) argv.flags.add(arg.slice(2));
+    else argv._.push(arg);
+  }
+  return argv;
 }
 
-const [, , command, ...rest] = process.argv;
-if (!command || command === 'help' || command === '--help' || command === '-h') {
+const [, , word, ...rest] = process.argv;
+if (!word || word === 'help' || word === '--help' || word === '-h') {
   usage();
   process.exit(0);
 }
-if (command === '--version' || command === '-v') {
+if (word === '--version' || word === '-v') {
   const { readFileSync } = await import('node:fs');
   const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
   say(pkg.version);
   process.exit(0);
 }
 
+const command = ALIASES[word] ?? word;
 const entry = COMMANDS[command];
 if (!entry) {
-  say(`${dim('unknown command')} ${command}\n`);
+  say(`${dim('unknown command')} ${word}\n`);
   usage();
   process.exit(1);
 }
@@ -56,8 +81,7 @@ if (!entry) {
 // One place where an unexpected failure becomes a sentence rather than a stack
 // trace. A CLI that prints a stack is telling its user to read its source.
 try {
-  const urlFlag = rest.indexOf('--url');
-  await entry.run({ url: urlFlag === -1 ? undefined : rest[urlFlag + 1] });
+  await entry.run(parse(rest));
 } catch (error) {
   die(error?.message ?? String(error));
 }

package/src/install.mjs

@@ -0,0 +1,168 @@
+// Making `quxcloud` a word your shell knows.
+//
+// `npx @quxkit/quxcloud <cmd>` is the right way to run something once. It is
+// the wrong way to run something ten times a day: eighteen characters of scope
+// on every line, a package re-resolved on every invocation, and a name that
+// does not match the one the docs use. So `login` — the one command that has
+// to be typed in full, because nothing is installed yet — leaves a `quxcloud`
+// behind.
+//
+// Not `npm i -g`: a global install needs whichever node the user happens to be
+// on, writes into a prefix that is root-owned on a Homebrew node, and breaks
+// when they switch nvm versions. Instead the package copies itself — it has no
+// dependencies, so a copy is the whole thing — beside its config and drops a
+// three-line shim next to it.
+//
+//   ~/.config/quxcloud/lib/src/index.mjs   the CLI itself
+//   ~/.config/quxcloud/bin/quxcloud        exec node <lib>/src/index.mjs "$@"
+//
+// Beside the key, in the directory the CLI already owns — and deliberately not
+// ~/.quxcloud, which would be the same path as the link file of a project
+// cloned into the home directory.
+//
+// The only thing left is PATH, which a child process cannot set for its
+// parent. We ask before touching a shell rc file, and when the answer is no
+// (or there is nobody to ask) we print the one line to add.
+
+import { appendFileSync, chmodSync, cpSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, delimiter, dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { configDir } from './config.mjs';
+import { ask, bold, dim, green, say } from './ui.mjs';
+
+export const binDir = () => join(configDir(), 'bin');
+const libDir = () => join(configDir(), 'lib');
+export const shimPath = () => join(binDir(), process.platform === 'win32' ? 'quxcloud.cmd' : 'quxcloud');
+
+/** The root of the package this process is running from. */
+const packageRoot = () => resolvePath(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * The same directory reached two ways has to compare equal.
+ *
+ * On macOS the temp dir is /var -> /private/var, and `import.meta.url` reports
+ * the resolved side while a configured path reports the symlink. Comparing the
+ * strings said "different", and `upgrade` from the installed copy then deleted
+ * the very files it was about to copy.
+ */
+const sameDir = (a, b) => {
+  const real = (p) => { try { return realpathSync(p); } catch { return resolvePath(p); } };
+  return real(a) === real(b);
+};
+
+const MARKER = '# added by quxcloud';
+
+/** Is the shim's directory already somewhere the shell will look? */
+export function onPath(env = process.env) {
+  const entries = (env.PATH ?? '').split(delimiter).filter(Boolean).map((p) => resolvePath(p));
+  return entries.includes(resolvePath(binDir()));
+}
+
+/**
+ * Copy the CLI beside the config and write the shim.
+ *
+ * Idempotent, and safe to run from the installed copy — which is what
+ * `quxcloud upgrade` does after npx has fetched a newer package.
+ */
+export function installShim() {
+  const source = packageRoot();
+  const lib = libDir();
+  mkdirSync(binDir(), { recursive: true });
+
+  if (!sameDir(source, lib)) {
+    // Staged, then swapped. Replacing rather than merging is the point — a
+    // file dropped in a later version has to disappear here too, or it stays
+    // loadable forever — but a copy that fails halfway must not leave the
+    // install gutted, so nothing is deleted until the new copy is complete.
+    const staged = `${lib}.incoming`;
+    rmSync(staged, { recursive: true, force: true });
+    mkdirSync(staged, { recursive: true });
+    cpSync(join(source, 'src'), join(staged, 'src'), { recursive: true });
+    cpSync(join(source, 'package.json'), join(staged, 'package.json'));
+    rmSync(lib, { recursive: true, force: true });
+    renameSync(staged, lib);
+  }
+
+  const entry = join(lib, 'src', 'index.mjs');
+  if (process.platform === 'win32') {
+    writeFileSync(shimPath(), `@echo off\r\nnode "${entry}" %*\r\n`);
+  } else {
+    writeFileSync(shimPath(), `#!/bin/sh\n${MARKER} — regenerated by \`quxcloud upgrade\`\nexec node "${entry}" "$@"\n`);
+    chmodSync(shimPath(), 0o755);
+  }
+  return { bin: binDir(), lib, version: version(lib) };
+}
+
+function version(lib) {
+  try { return JSON.parse(readFileSync(join(lib, 'package.json'), 'utf8')).version; } catch { return null; }
+}
+
+/** The rc file this person's shell actually reads, and the line to put in it. */
+export function shellProfile(env = process.env, platform = process.platform) {
+  if (platform === 'win32') return null;
+  const shell = basename(env.SHELL ?? '');
+  const bin = binDir();
+  if (shell === 'fish') {
+    return { file: join(homedir(), '.config', 'fish', 'config.fish'), line: `fish_add_path ${bin}` };
+  }
+  if (shell === 'bash') {
+    // macOS Terminal opens login shells, which read .bash_profile and never
+    // .bashrc. Prefer whichever already exists.
+    const profile = join(homedir(), '.bash_profile');
+    const rc = join(homedir(), '.bashrc');
+    const file = platform === 'darwin' ? (existsSync(rc) && !existsSync(profile) ? rc : profile) : rc;
+    return { file, line: `export PATH="${bin}:$PATH"` };
+  }
+  return { file: join(homedir(), `.${shell || 'zsh'}rc`), line: `export PATH="${bin}:$PATH"` };
+}
+
+/** True if this rc file already puts the shim on PATH. */
+export function profileHasLine(file, line) {
+  try { return readFileSync(file, 'utf8').includes(line); } catch { return false; }
+}
+
+export function writeProfile(file, line) {
+  mkdirSync(dirname(file), { recursive: true });
+  appendFileSync(file, `\n${MARKER}\n${line}\n`);
+}
+
+/**
+ * Install, then make sure the shell can find it — printing what happened.
+ *
+ * `consent` is asked only when there is a terminal to ask; unattended, we
+ * install and print, and change nobody's dotfiles behind their back.
+ */
+export async function installAndAnnounce({ interactive = process.stdin.isTTY } = {}) {
+  const installed = installShim();
+  const { bin } = installed;
+  const done = (path) => ({ ...installed, path });
+
+  if (onPath()) {
+    say(`${green('Installed.')} ${bold('quxcloud')} is on your PATH — the scope was only ever needed for ${bold('login')}.`);
+    return done('already');
+  }
+
+  const profile = shellProfile();
+  if (profile && profileHasLine(profile.file, profile.line)) {
+    say(`${green('Installed.')} ${bold(profile.file)} already adds it — open a new terminal and ${bold('quxcloud')} is a command.`);
+    return done('pending-reload');
+  }
+
+  if (profile && interactive) {
+    const answer = (await ask(`Add ${bold(bin)} to your PATH in ${bold(profile.file)}? ${dim('[Y/n]')} `)).toLowerCase();
+    if (answer === '' || answer === 'y' || answer === 'yes') {
+      writeProfile(profile.file, profile.line);
+      say(`${green('Installed.')} Open a new terminal, or run ${bold(profile.line)} in this one.`);
+      say(dim('From then on it is `quxcloud pull`, not the whole scope.'));
+      return done('written');
+    }
+  }
+
+  say(`${green('Installed')} to ${dim(bin)}. Add it to your PATH to drop the scope:`);
+  say('');
+  say(`  ${bold(profile?.line ?? `set PATH=${bin};%PATH%`)}`);
+  say('');
+  return done('printed');
+}