@drael/code 0.2.0 → 0.4.0

package/README.md

@@ -1,84 +1,48 @@
 # @drael/code
 
-Points a coding client at [Drael](https://drael.sh). One command, and it asks before it
-writes.
+Points a coding client at [Drael](https://drael.sh).
 
 ```sh
 npx @drael/code
 ```
 
-It asks for your key and which client, and nothing else. Both can be flags instead:
+It asks for your key and which client, writes that client's own configuration file, and
+nothing else. Whatever it touches it copies first.
 
 ```sh
-npx @drael/code --key dk-YOUR-KEY --client kilo
+npx @drael/code --list        what it knows how to configure, and where
+npx @drael/code --dry-run     exactly what it would write, changing nothing
+npx @drael/code --uninstall   every file it changed, put back
+npx @drael/code --help        the flags
 ```
 
-## What it configures
-
-| Client     | File                          |
-| ---------- | ----------------------------- |
-| `opencode` | `~/.config/opencode/opencode.json` |
-| `kilo`     | `~/.config/kilo/kilo.jsonc`   |
-| `env`      | `~/.config/drael/env.sh`, for anything reading `OPENAI_BASE_URL` |
-
-All three are written `0600`, because a file holding an API key is not a file other
-accounts on the machine should read.
-
-The `kilo` file is **merged** rather than replaced: it is the whole extension's
-configuration and not ours, so the other providers and everything else in it are kept.
-
-## Undoing it
-
-```sh
-npx @drael/code --uninstall
-```
-
-Every file is copied before it is written, under `~/.local/state/drael/installer`.
-Uninstall puts the originals back byte for byte and removes the files that did not exist
-before. Installing twice keeps the **first** copy, so what an uninstall restores is the
-state before this ever touched the file.
-
-`--dry-run` prints exactly what would be written and changes nothing, including the copy.
-
-## The flags
-
-| Flag          | What it does                                                     |
-| ------------- | ---------------------------------------------------------------- |
-| `--key`       | The API key. Falls back to `DRAEL_KEY`, then to a prompt.         |
-| `--client`    | `opencode`, `kilo` or `env`. Without it you are asked.            |
-| `--host`      | For a local build or your own box. Defaults to `https://drael.sh`. |
-| `--list`      | Prints what it knows how to configure, and exits.                |
-| `--dry-run`   | Prints what would be written, and changes nothing.               |
-| `--uninstall` | Restores every file it changed, and exits.                       |
+Those four answer for themselves rather than being copied out here, so this page cannot
+go stale about which clients are supported, where their files live, or what the flags are.
 
 ## Why npx rather than `curl | sh`
 
 Piping a URL into a shell is exactly the pattern this product's own users are right to
-refuse. npx is already on the machine of anybody running an editor extension, and it
-makes Windows work without a second implementation to keep in step.
+refuse. npx is already on the machine of anybody running an editor extension, and it makes
+Windows work without a second implementation to keep in step.
 
-It makes one network call: `GET /v1/models` against the host it is configuring, to write
-the id that host actually serves rather than one assumed here. A host that does not
-answer is no reason to refuse to configure anything, so the published id stands in.
-
-That call is not a check. The last thing it prints is the `curl` that verifies the host
-and the key, for you to run yourself.
-
-The source is one file with one dependency, and it is short enough to read in a sitting.
-The people most right to distrust an opaque installer are this product's own users, so it
-earns the trust by being readable rather than by asking.
+It asks for no privilege, and it writes nothing outside the configuration file of the
+client you chose. The source is one file, short enough to read in a sitting: the people
+most right to distrust an opaque installer are this product's own users, so it earns the
+trust by being readable rather than by asking.
 
 ## Doing it by hand
 
-There is nothing privileged in what it writes. Any OpenAI-compatible client takes the
-same two values directly:
+There is nothing privileged in what it writes. The API is OpenAI-compatible, so any client
+takes a base URL and a key directly:
 
 ```sh
 export OPENAI_BASE_URL="https://drael.sh/v1"
 export OPENAI_API_KEY="dk-YOUR-KEY"
 ```
 
-The model id is `drael-v1`, and `GET /v1/models` is where it comes from. Full documentation at
-[drael.sh/docs/install](https://drael.sh/docs/install).
+## Everything else
+
+[drael.sh/docs/install](https://drael.sh/docs/install) is the documentation, and it is the
+copy that is kept current.
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drael/code",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Point your coding client at Drael.",
   "type": "module",
   "bin": {

package/src/code.js

@@ -41,12 +41,15 @@ import { isCancel, PasswordPrompt, SelectPrompt } from '@clack/core'
 
 /* ─────────────────────────────────────────────────────────────  where things live  ── */
 
-const CONFIG_HOME =
-  process.env.XDG_CONFIG_HOME ??
-  (platform() === 'win32'
-    ? join(process.env.APPDATA ?? homedir(), 'Config')
-    : join(homedir(), '.config'))
-
+// Home-relative on every platform, Windows included. The clients here document
+// `~/.config/<them>` literally and read nowhere else, so the earlier `%APPDATA%\\Config`
+// branch wrote a valid file into a directory nothing opens: the worst failure this tool
+// has, because it reports success.
+const CONFIG_HOME = process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config')
+
+// The backups do not follow, and that is deliberate: this directory is ours rather than a
+// client's, so it was never in the wrong place, and moving it would strand the records
+// written by an earlier version. An uninstall that cannot find them is not an uninstall.
 const STATE_HOME =
   process.env.XDG_STATE_HOME ??
   (platform() === 'win32'
@@ -55,8 +58,8 @@ const STATE_HOME =
 
 const BACKUPS = join(STATE_HOME, 'drael', 'installer')
 
-// Kilo documents this literal path on every platform, Windows included, so this one
-// does not go through CONFIG_HOME the way the others do.
+// Kilo documents this literal path, so unlike the others it is not moved by
+// XDG_CONFIG_HOME either.
 const KILO_CONFIG = join(homedir(), '.config', 'kilo', 'kilo.jsonc')
 
 // There is one origin (ADR 0017), and this package is published by the people who run
@@ -279,17 +282,24 @@ const askClient = () =>
  * product itself. The one call this makes, and the only one: it is to the host being
  * configured, with the key being configured, and a host that does not answer is not a
  * reason to refuse to write anything, so the published id stands in.
+ *
+ * It is also the only check the reader needs, which is why the frame reports what came
+ * back instead of handing out a curl line: that line carried the key in clear text, on
+ * screen and into the scrollback, one row under the prompt that had just masked it.
  */
-async function servedModel(host, key) {
+async function askHost(host, key) {
   try {
     const response = await fetch(`${host}/v1/models`, {
       headers: { Authorization: `Bearer ${key}` },
       signal: AbortSignal.timeout(4000),
     })
+    if (response.status === 401 || response.status === 403) {
+      return { refused: true }
+    }
     const served = (await response.json())?.data?.[0]?.id
-    return typeof served === 'string' && served ? served : MODEL
+    return { model: typeof served === 'string' && served ? served : null }
   } catch {
-    return MODEL
+    return {}
   }
 }
 
@@ -327,8 +337,9 @@ async function install(args) {
     fail(`unknown client: ${name} (try --list)`)
   }
 
+  const answer = await askHost(host, key)
   const file = client.file()
-  const contents = client.contents(host, key, await servedModel(host, key))
+  const contents = client.contents(host, key, answer.model ?? MODEL)
 
   // An answered prompt leaves its frame on screen and needs a gap after it. With every
   // answer given as a flag there was no frame, and the masthead's own gap is already it.
@@ -367,11 +378,25 @@ async function install(args) {
   console.log()
   console.log(rule())
   console.log()
-  console.log(row('check it', dim(`curl ${host}/v1/models -H "Authorization: Bearer ${key}"`)))
+  console.log(row('the host', dim(`${host}/v1, ${said(answer)}`)))
+  if (answer.refused) {
+    console.log(under(dim(`create one at ${host}/developers, then run this again`)))
+  }
   console.log(row('undo it', dim('npx @drael/code --uninstall')))
   console.log()
 }
 
+/** What the one call came back with, in the frame's own voice. */
+function said(answer) {
+  if (answer.refused) {
+    return 'which refused that key'
+  }
+  if (answer.model) {
+    return `serving ${answer.model}`
+  }
+  return `which did not answer, so ${MODEL} was written`
+}
+
 /**
  * Every write is preceded by a copy. An uninstall that cannot put the file back is not
  * an uninstall, it is a deletion with better manners. It reports what it found rather
@@ -443,6 +468,26 @@ function uninstall(args) {
   console.log()
 }
 
+/**
+ * The flags, from the tool rather than from a page about the tool. The README points here
+ * instead of repeating any of it, and a test holds this list to the flags the code reads.
+ */
+function help() {
+  masthead('into the editor you already use')
+  for (const [flag, said] of [
+    ['--key', 'the API key. Falls back to DRAEL_KEY, then to a prompt'],
+    ['--client', 'which one to configure. Without it, you are asked'],
+    ['--host', `for a local build or your own box. Defaults to ${DRAEL}`],
+    ['--list', 'what it knows how to configure, and where'],
+    ['--dry-run', 'exactly what it would write, changing nothing'],
+    ['--uninstall', 'every file it changed, put back'],
+    ['--help', 'this'],
+  ]) {
+    console.log(row(flag, dim(said)))
+  }
+  console.log()
+}
+
 function list() {
   console.log()
   for (const [name, client] of Object.entries(clients)) {
@@ -473,11 +518,17 @@ function parse(argv) {
     const arg = argv[i]
     if (!arg.startsWith('--')) continue
     const name = arg.slice(2)
-    if (['list', 'uninstall', 'dry-run'].includes(name)) {
+    if (['list', 'uninstall', 'dry-run', 'help'].includes(name)) {
       parsed[name] = true
       continue
     }
-    parsed[name] = argv[++i]
+    // `--client --key dk-…` used to swallow the next flag as the value and then report
+    // `unknown client: --key`, which names neither the mistake nor the fix.
+    const value = argv[++i]
+    if (value === undefined || value.startsWith('--')) {
+      fail(`--${name} needs a value`)
+    }
+    parsed[name] = value
   }
   return parsed
 }
@@ -488,7 +539,9 @@ process.on('exit', () => process.stdout.write('\u001b[?25h'))
 
 const args = parse(process.argv.slice(2))
 
-if (args.list) {
+if (args.help) {
+  help()
+} else if (args.list) {
   list()
 } else if (args.uninstall) {
   uninstall(args)