@drael/code 0.1.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@drael/code",
+  "version": "0.1.0",
+  "description": "Point your coding client at Drael.",
+  "type": "module",
+  "bin": {
+    "drael": "src/code.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "ci": "node --check src/code.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/core": "^1.0.0"
+  }
+}

package/src/code.js

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+/**
+ * Drael, into the editor you already use.
+ *
+ *   npx @drael/code                       interactive
+ *   npx @drael/code --key … --client …    answered up front
+ *   npx @drael/code --list                what it knows how to configure
+ *   npx @drael/code --dry-run …           print what it would write, change nothing
+ *   npx @drael/code --uninstall           restore every file it changed
+ *
+ * It runs through npx rather than `curl | sh` deliberately. Piping a URL into a
+ * shell is exactly the pattern this product's own users are right to refuse, and
+ * npx is already on the machine of anybody with an editor extension. It also makes
+ * Windows work without a second implementation.
+ *
+ * It writes nothing but the target client's own configuration file, copies what it
+ * touches before touching it, and asks for no privilege. The docs link to this file
+ * on purpose, because an installer earns trust by being short enough to read.
+ */
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir, platform } from 'node:os'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+
+/**
+ * `@clack/core` rather than `@clack/prompts`: the latter draws its own rail and
+ * colours its own symbols, and both are its identity rather than ours. Core is the
+ * half underneath, which reads raw mode, tracks the keys, validates and carries the
+ * cancel symbol, and asks each prompt to draw itself. The drawing here is Drael's.
+ */
+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'))
+
+const STATE_HOME =
+  process.env.XDG_STATE_HOME ??
+  (platform() === 'win32'
+    ? join(process.env.LOCALAPPDATA ?? homedir(), 'State')
+    : join(homedir(), '.local', 'state'))
+
+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.
+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
+// it. Asking for the address was the installer failing to know its own address.
+const DRAEL = 'https://drael.sh'
+
+/* ──────────────────────────────────────────────────────────────────  the clients  ── */
+
+/**
+ * What it knows how to configure. A client is added when real usage justifies it, not
+ * pre-emptively: each one is a format that can change under us, and a client nobody
+ * here runs is a client we would break silently.
+ *
+ * `merges` is the difference between a file that is ours and a file we are a guest in.
+ */
+const clients = {
+  opencode: {
+    label: 'OpenCode',
+    file: () => join(CONFIG_HOME, 'opencode', 'opencode.json'),
+    contents: (host, key) =>
+      json({
+        $schema: 'https://opencode.ai/config.json',
+        provider: {
+          drael: {
+            npm: '@ai-sdk/openai-compatible',
+            name: 'Drael',
+            options: { baseURL: `${host}/v1`, apiKey: key },
+            models: { drael: { name: 'Drael' } },
+          },
+        },
+        model: 'drael/drael',
+      }),
+  },
+
+  kilo: {
+    label: 'Kilo Code',
+    merges: true,
+    file: () => KILO_CONFIG,
+    contents: (host, key) => {
+      const existing = readJson(KILO_CONFIG)
+      return json({
+        ...existing,
+        $schema: 'https://app.kilo.ai/config.json',
+        provider: {
+          ...existing.provider,
+          drael: {
+            options: { baseURL: `${host}/v1`, apiKey: key },
+            models: { drael: { name: 'Drael' } },
+          },
+        },
+        model: 'drael/drael',
+      })
+    },
+  },
+
+  env: {
+    label: 'anything reading OPENAI_BASE_URL',
+    file: () => join(CONFIG_HOME, 'drael', 'env.sh'),
+    contents: (host, key) =>
+      [
+        '# Drael. Source this, or add it to your shell profile.',
+        `export OPENAI_BASE_URL="${host}/v1"`,
+        `export OPENAI_API_KEY="${key}"`,
+        '# Some clients read the older name.',
+        `export OPENAI_API_BASE="${host}/v1"`,
+        '',
+      ].join('\n'),
+    after: (file) => `add this to your shell profile\n${dim(`. ${sourceable(file)}`)}`,
+  },
+}
+
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`
+
+/**
+ * Kilo's file is the whole extension's configuration and not ours, so ours is merged
+ * into what is already there. A file that does not parse is treated as absent rather
+ * than guessed at: JSONC allows comments, and a parser guessing at them writes back a
+ * mangled config. The copy under BACKUPS still holds the original, and `parses` below
+ * is what lets the frame say so before it writes.
+ */
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+function parses(file) {
+  if (!existsSync(file)) {
+    return true
+  }
+  try {
+    JSON.parse(readFileSync(file, 'utf8'))
+    return true
+  } catch {
+    return false
+  }
+}
+
+/* ──────────────────────────────────────────────────────────────────  the drawing  ── */
+
+/**
+ * The system is monochrome and its structure is a ruled grid with markers at the
+ * crossings, never a card and never a fill (`packages/ui/DESIGN.md`). A page has three
+ * values for that, `--figure`, `--secondary` and `--tertiary`; a terminal has weight
+ * instead, so these three stand in for them in the same order.
+ *
+ * All of it goes plain when stdout is not a terminal or NO_COLOR is set, because a
+ * piped log is read by something that does not draw.
+ */
+const styled = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+const bold = (text) => (styled ? `\u001b[1m${text}\u001b[22m` : text)
+const dim = (text) => (styled ? `\u001b[2m${text}\u001b[22m` : text)
+
+// The label column, wide enough for the longest label with a gutter after it.
+const LABEL = 13
+const WIDTH = Math.max(48, Math.min(process.stdout.columns || 80, 78))
+
+/**
+ * A row of the grid: the label on the left rail, what it names on the right. Content
+ * that runs to a second line is indented into the same column, so the rail stays a rail.
+ */
+function row(label, content = '') {
+  const gutter = ' '.repeat(LABEL + 2)
+  return `  ${dim(label.padEnd(LABEL))}${String(content).replaceAll('\n', `\n${gutter}`)}`
+}
+
+/** A row with no label, sitting under the one above it. */
+const under = (content) => row('', content)
+
+/** A hairline, marked where the label column crosses it. */
+const rule = () => dim(`  ${'─'.repeat(LABEL - 1)}┬${'─'.repeat(WIDTH - LABEL - 3)}`)
+
+/** A home-relative path is what the reader recognises; the absolute one is a wall. */
+const tilde = (path) => (path.startsWith(homedir()) ? `~${path.slice(homedir().length)}` : path)
+
+/**
+ * For a line that gets pasted into a shell. A `~` inside quotes is not expanded and an
+ * unquoted path breaks on a space; `$HOME` survives both.
+ */
+const sourceable = (path) =>
+  path.startsWith(homedir()) ? `"$HOME${path.slice(homedir().length)}"` : `"${path}"`
+
+function masthead(caption) {
+  console.log()
+  console.log(`  ${bold('Drael.sh'.padEnd(LABEL))}${dim(caption)}`)
+  console.log(rule())
+  console.log()
+}
+
+/* ──────────────────────────────────────────────────────────────────  the prompts  ── */
+
+/**
+ * Each prompt draws its own block and core redraws it on every key. `state` is what
+ * the prompt is doing, and the only two frames that differ are the one being answered
+ * and the one already answered, which collapses to the answer alone.
+ */
+async function ask(prompt) {
+  if (!process.stdin.isTTY) {
+    // Without a terminal a prompt waits forever, node exits on the unsettled await,
+    // and nothing is said about the flags that would have avoided the question.
+    fail('there is no terminal to ask on: pass --key and --client')
+  }
+  const answer = await prompt.prompt()
+  if (isCancel(answer)) {
+    console.log(row('', dim('cancelled, nothing was written')))
+    console.log()
+    process.exit(1)
+  }
+  return answer
+}
+
+const askKey = (host) =>
+  ask(
+    new PasswordPrompt({
+      mask: '▪',
+      validate: (value) => (value.startsWith('dk-') ? undefined : 'a Drael key starts with dk-'),
+      render() {
+        if (this.state === 'submit') {
+          return row('api key', dim(this.masked))
+        }
+        return [
+          row('api key', this.userInputWithCursor),
+          under(dim(this.error || `create one at ${host}/developers`)),
+        ].join('\n')
+      },
+    }),
+  )
+
+const askClient = () =>
+  ask(
+    new SelectPrompt({
+      options: Object.entries(clients).map(([value, client]) => ({ value, client })),
+      initialValue: detected(),
+      render() {
+        if (this.state === 'submit') {
+          return row('client', dim(this.value))
+        }
+        return this.options
+          .map(({ value, client }, index) => {
+            const chosen = index === this.cursor
+            const name = `${chosen ? '▸ ' : '  '}${value.padEnd(9)} `
+            const said = `${client.label}${found(client) ? ' · on this machine' : ''}`
+            return row(index === 0 ? 'client' : '', chosen ? bold(name) + said : dim(name + said))
+          })
+          .join('\n')
+      },
+    }),
+  )
+
+/**
+ * Whether the client's own directory is on this machine. It is a hint and never a gate:
+ * a fresh install may not have written its directory yet, so every client stays on the
+ * list and detection only decides which one the cursor starts on.
+ */
+function found(client) {
+  return existsSync(dirname(client.file()))
+}
+
+function detected() {
+  return Object.entries(clients).find(([, client]) => found(client))?.[0] ?? 'opencode'
+}
+
+/* ────────────────────────────────────────────────────────────────────  installing  ── */
+
+async function install(args) {
+  masthead('into the editor you already use')
+
+  const host = (args.host ?? process.env.DRAEL_HOST ?? DRAEL).replace(/\/+$/, '')
+  if (!/^https?:\/\//.test(host)) {
+    fail('the host must start with https:// or http://')
+  }
+
+  const key = (args.key ?? process.env.DRAEL_KEY ?? (await askKey(host))).trim()
+  if (!key.startsWith('dk-')) {
+    fail('that does not look like a Drael key; they start with dk-')
+  }
+
+  const name = (args.client ?? (await askClient())).trim()
+  const client = clients[name]
+  if (!client) {
+    fail(`unknown client: ${name} (try --list)`)
+  }
+
+  const file = client.file()
+  const contents = client.contents(host, key)
+
+  // 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.
+  if (!(args.key ?? process.env.DRAEL_KEY) || !args.client) {
+    console.log()
+  }
+
+  if (args['dry-run']) {
+    console.log(row(client.merges ? 'would merge' : 'would write', tilde(file)))
+    console.log()
+    console.log(contents.trimEnd().replace(/^/gm, ' '.repeat(LABEL + 2)))
+    console.log()
+    console.log(row('', dim('nothing was written')))
+    console.log()
+    return
+  }
+
+  const kept = backup(file)
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, contents, { mode: 0o600 })
+  chmodSync(file, 0o600)
+
+  console.log(row(client.merges ? 'merged' : 'wrote', tilde(file)))
+  if (client.merges && !parses(file)) {
+    console.log(under(dim('it was not plain JSON, so it was replaced rather than merged')))
+  }
+  console.log(row(kept.label, dim(kept.detail)))
+  if (client.after) {
+    console.log()
+    console.log(row('and then', client.after(file)))
+  }
+
+  console.log()
+  console.log(rule())
+  console.log()
+  console.log(row('check it', dim(`curl ${host}/v1/models -H "Authorization: Bearer ${key}"`)))
+  console.log(row('undo it', dim('npx @drael/code --uninstall')))
+  console.log()
+}
+
+/**
+ * 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
+ * than printing it, so the frame says the path once.
+ */
+function backup(file) {
+  mkdirSync(BACKUPS, { recursive: true })
+  const slug = file.replace(/[\\/:]/g, '_')
+
+  // Only the FIRST record is kept. What an uninstall restores is the state before this
+  // installer ever touched the file, so running it twice must not overwrite the
+  // original with our own output, and must not leave two records that disagree about
+  // whether the file existed.
+  if (existsSync(join(BACKUPS, slug)) || existsSync(join(BACKUPS, `${slug}.absent`))) {
+    return { label: 'kept', detail: 'the original was already recorded, from an earlier run' }
+  }
+
+  if (existsSync(file)) {
+    copyFileSync(file, join(BACKUPS, slug))
+    // The original path beside the copy, because a slug is not reversible into a path
+    // and guessing one is how an uninstall writes to the wrong place.
+    writeFileSync(join(BACKUPS, `${slug}.path`), file)
+    return { label: 'copied', detail: `the original, to ${tilde(BACKUPS)}` }
+  }
+
+  // The file did not exist, so restoring means removing what we created.
+  writeFileSync(join(BACKUPS, `${slug}.absent`), file)
+  return { label: 'new', detail: 'it did not exist before, and uninstall removes it' }
+}
+
+function uninstall(args) {
+  masthead('putting back what it changed')
+
+  if (!existsSync(BACKUPS)) {
+    fail(`nothing to restore: no record at ${tilde(BACKUPS)}`)
+  }
+
+  let restored = 0
+  for (const entry of readdirSync(BACKUPS)) {
+    if (entry.endsWith('.path')) continue
+    const saved = join(BACKUPS, entry)
+
+    if (entry.endsWith('.absent')) {
+      const file = read(saved)
+      if (existsSync(file)) {
+        if (!args['dry-run']) rmSync(file)
+        console.log(row('removed', tilde(file)))
+        restored++
+      }
+      if (!args['dry-run']) rmSync(saved)
+      continue
+    }
+
+    // The slug is not reversible into a path on its own, so the original path is stored
+    // beside the copy rather than guessed from the name.
+    const file = read(`${saved}.path`)
+    if (!file) continue
+    if (!args['dry-run']) copyFileSync(saved, file)
+    console.log(row('restored', tilde(file)))
+    restored++
+    if (!args['dry-run']) {
+      rmSync(saved)
+      rmSync(`${saved}.path`)
+    }
+  }
+
+  console.log()
+  console.log(row('', dim(`${restored} ${restored === 1 ? 'file' : 'files'} put back`)))
+  console.log()
+}
+
+function list() {
+  console.log()
+  for (const [name, client] of Object.entries(clients)) {
+    console.log(row(name, `${dim(tilde(client.file()).padEnd(34))} ${client.label}`))
+  }
+  console.log()
+}
+
+/* ───────────────────────────────────────────────────────────────────────  running  ── */
+
+function read(path) {
+  try {
+    return readFileSync(path, 'utf8').trim()
+  } catch {
+    return ''
+  }
+}
+
+function fail(message) {
+  console.log(row('', bold(message)))
+  console.log()
+  process.exit(1)
+}
+
+function parse(argv) {
+  const parsed = {}
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (!arg.startsWith('--')) continue
+    const name = arg.slice(2)
+    if (['list', 'uninstall', 'dry-run'].includes(name)) {
+      parsed[name] = true
+      continue
+    }
+    parsed[name] = argv[++i]
+  }
+  return parsed
+}
+
+// A prompt hides the cursor while it is up, and an exit that is not the prompt's own
+// leaves it hidden in the terminal the reader goes back to.
+process.on('exit', () => process.stdout.write('\u001b[?25h'))
+
+const args = parse(process.argv.slice(2))
+
+if (args.list) {
+  list()
+} else if (args.uninstall) {
+  uninstall(args)
+} else {
+  await install(args)
+}