lecodes-cli 0.20.1 → 1.0.0

package/src/commands/pn.ts

@@ -1,12 +1,10 @@
-import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs"
-import { join } from "node:path"
+import { upsertDotEnv } from "../project/env"
 import {
   createPushKey, forgetPushDevice, listPushDevices, listPushKeys, revokePushKey, sendPush,
   type PushDevice, type PushSendPayload,
-} from "../api"
-import { loadConfig, requireApiUrl, requireToken } from "../config"
-import { findProjectRoot, readManifest } from "../manifest"
-import { CliError, c, confirm, flagBool, flagStr, info, log, success, warn, type Args } from "../util"
+} from "../platform/api"
+import { CliError, UsageError, bool, c, confirm, defineCommand, info, log, num, relativeTime, str, success, table, warn } from "../cli"
+import { linkedProject, type LinkedProject } from "./shared"
 
 /*
  * `lecodes pn` — push notifications for this project (docs/push-plan.md). Named `pn` because
@@ -26,100 +24,75 @@ import { CliError, c, confirm, flagBool, flagStr, info, log, success, warn, type
 
 const ENV_VAR = "LECODES_PUSH_KEY"
 
-type Context = { root: string, uuid: string, name: string, apiUrl: string, token: string }
-
-const context = (): Context => {
-  const root = findProjectRoot(process.cwd())
-  const manifest = readManifest(root)
-  const config = loadConfig()
-  return { root, uuid: manifest.uuid, name: manifest.name, apiUrl: requireApiUrl(config), token: requireToken(config) }
-}
-
-/** A compact "3h ago" — absolute timestamps make these tables unreadable at a glance. */
-const ago = (iso: string | null): string => {
-  if (!iso) return c.dim("never")
-  const ms = Date.now() - new Date(iso).getTime()
-  if (!Number.isFinite(ms)) return c.dim("—")
-  const mins = Math.round(ms / 60_000)
-  if (mins < 1) return "just now"
-  if (mins < 60) return `${mins}m ago`
-  const hours = Math.round(mins / 60)
-  if (hours < 24) return `${hours}h ago`
-  return `${Math.round(hours / 24)}d ago`
-}
-
-// Column widths must count PRINTED characters: on a TTY the cells carry ANSI color codes, and
-// padEnd would count those too — every colored column drifting a few chars wide.
-const ANSI = /\x1b\[[0-9;]*m/g
-const printed = (s: string) => s.replace(ANSI, "").length
-
-/** Print rows as aligned columns (last column unpadded so colors don't drag trailing spaces). */
-const table = (rows: string[][]) => {
-  const widths = rows[0].map((_, i) => Math.max(...rows.map(r => printed(r[i] ?? ""))))
-  for (const row of rows) {
-    const cells = row.map((cell, i) =>
-      i === row.length - 1 ? cell : cell + " ".repeat(Math.max(0, widths[i] - printed(cell))))
-    log("  " + cells.join("  "))
-  }
-}
-
-/** Comma-separated list flag. parseArgs keeps only the LAST of a repeated `--user`, so repeats
+/** Comma-separated list flag. The parser keeps only the LAST of a repeated `--user`, so repeats
  *  would silently drop targets — commas are the form that can't lose one. */
-const listFlag = (args: Args, ...keys: string[]): string[] => {
-  const raw = flagStr(args, ...keys)
-  if (!raw) return []
-  return [ ...new Set(raw.split(",").map(s => s.trim()).filter(Boolean)) ]
-}
+const listOf = (raw: string | undefined): string[] =>
+  raw ? [ ...new Set(raw.split(",").map(s => s.trim()).filter(Boolean)) ] : []
 
-/* ---------------------------------------- send ---------------------------------------- */
-
-/** `lecodes pn send --title … [--user u42] [--to pa_…]` — a real send through the relay,
- *  authenticated with your own token. Targets are the same ones a production server uses. */
-const pnSend = async (args: Args) => {
-  const ctx = context()
+const confirmFlag = { yes: bool("skip the confirmation", { alias: "y" }) }
 
-  const title = flagStr(args, "title", "t") ?? args._[1]
-  if (!title) throw new CliError('A title is required: lecodes pn send --title "Order shipped" --user u42')
+/* ---------------------------------------- send ---------------------------------------- */
 
-  const users = listFlag(args, "user", "users", "u")
-  const to = listFlag(args, "to", "address", "addresses")
-  if (users.length === 0 && to.length === 0) {
-    throw new CliError("Nothing to send to — pass --user <id> (from Push.register({ user })) or --to <pa_…>. `lecodes pn devices` lists both.")
-  }
+/** A real send through the relay, authenticated with your own token. Targets are the same ones a
+ *  production server uses. */
+const send = defineCommand({
+  name: "send",
+  summary: "Send a notification (uses your login — no key needed)",
+  usage: "[title]",
+  description: "Targets are what a production server sends to: --user ids from Push.register({ user }) and/or --to device addresses (`lecodes pn devices` lists both). The title may also be given as the first positional.",
+  flags: {
+    title: str("the notification title", { alias: "t", value: "<s>" }),
+    body: str("second line", { alias: "b", value: "<s>" }),
+    url: str("deep link (also arrives as app.launchUrl)", { value: "<s>" }),
+    user: str("target Push.register({ user }) ids, comma-separated", { alias: "u", value: "<ids>" }),
+    to: str("target addresses, comma-separated", { value: "<pa_…>" }),
+    badge: num("app icon badge"),
+    data: str("your JSON payload (≤ 2 KB)", { value: "<json>" }),
+  },
+  examples: ['lecodes pn send --title "Order shipped" --user u42', 'lecodes pn send --title "Hi" --to pa_abc --body "second line"'],
+  run: async ({ args, flags }) => {
+    const { apiUrl, token, manifest } = linkedProject()
+
+    const title = flags.title ?? args[0]
+    if (!title) throw new UsageError('A title is required: lecodes pn send --title "Order shipped" --user u42')
+
+    const users = listOf(flags.user)
+    const to = listOf(flags.to)
+    if (users.length === 0 && to.length === 0) {
+      throw new CliError("Nothing to send to — pass --user <id> (from Push.register({ user })) or --to <pa_…>. `lecodes pn devices` lists both.")
+    }
 
-  const badgeRaw = flagStr(args, "badge")
-  const badge = badgeRaw === undefined ? undefined : Number(badgeRaw)
-  if (badge !== undefined && !Number.isInteger(badge)) throw new CliError(`--badge must be a whole number (got "${badgeRaw}")`)
+    if (flags.badge !== undefined && !Number.isInteger(flags.badge)) throw new CliError(`--badge must be a whole number (got "${flags.badge}")`)
 
-  const dataRaw = flagStr(args, "data")
-  let data: Record<string, unknown> | undefined
-  if (dataRaw !== undefined) {
-    try { data = JSON.parse(dataRaw) as Record<string, unknown> } catch { throw new CliError("--data must be a JSON object, e.g. --data '{\"orderId\":42}'") }
-    if (!data || typeof data !== "object" || Array.isArray(data)) throw new CliError("--data must be a JSON object, e.g. --data '{\"orderId\":42}'")
-  }
+    let data: Record<string, unknown> | undefined
+    if (flags.data !== undefined) {
+      try { data = JSON.parse(flags.data) as Record<string, unknown> } catch { throw new CliError("--data must be a JSON object, e.g. --data '{\"orderId\":42}'") }
+      if (!data || typeof data !== "object" || Array.isArray(data)) throw new CliError("--data must be a JSON object, e.g. --data '{\"orderId\":42}'")
+    }
 
-  const payload: PushSendPayload = {
-    title,
-    body: flagStr(args, "body", "b"),
-    url: flagStr(args, "url"),
-    users: users.length ? users : undefined,
-    to: to.length ? to : undefined,
-    data,
-    badge,
-  }
+    const payload: PushSendPayload = {
+      title,
+      body: flags.body,
+      url: flags.url,
+      users: users.length ? users : undefined,
+      to: to.length ? to : undefined,
+      data,
+      badge: flags.badge,
+    }
 
-  const result = await sendPush(ctx.apiUrl, ctx.token, ctx.uuid, payload)
+    const result = await sendPush(apiUrl, token, manifest.uuid, payload)
 
-  if (result.sent > 0) success(`Sent to ${result.sent} device${result.sent === 1 ? "" : "s"}.`)
-  if (result.failed.length === 0) {
-    if (result.sent === 0) {
-      warn("Matched 0 devices — nobody with that user id has registered. Run `lecodes pn devices` to see who has.")
+    if (result.sent > 0) success(`Sent to ${result.sent} device${result.sent === 1 ? "" : "s"}.`)
+    if (result.failed.length === 0) {
+      if (result.sent === 0) {
+        warn("Matched 0 devices — nobody with that user id has registered. Run `lecodes pn devices` to see who has.")
+      }
+      return
     }
-    return
-  }
-  warn(`${result.failed.length} failed:`)
-  for (const failure of result.failed) log(`  ${c.dim(failure.address)}  ${c.red(failure.reason)}`)
-}
+    warn(`${result.failed.length} failed:`)
+    for (const failure of result.failed) log(`  ${c.dim(failure.address)}  ${c.red(failure.reason)}`)
+  },
+})
 
 /* -------------------------------------- devices --------------------------------------- */
 
@@ -128,178 +101,162 @@ const deviceLabel = (device: PushDevice): string => {
   return `${device.platform}${env}`
 }
 
-/** `lecodes pn devices [--user u42] [--forget pa_…]` — the registration ledger. Raw OS tokens
- *  never leave the backend, so this is address + who/where/when only. --forget drops a dead row
- *  (rotated token, wrong project) that would otherwise sit here forever and fail every send. */
-const pnDevices = async (args: Args) => {
-  const ctx = context()
-  const user = flagStr(args, "user", "u")
-
-  const forget = flagStr(args, "forget")
-  if (forget) {
-    if (!flagBool(args, "yes", "y")) {
-      warn(`Forgetting ${c.bold(forget)} — sends to this address stop immediately. The device gets a NEW address on its next Push.register().`)
-      if (!await confirm("Forget it?")) return info("Cancelled.")
+/** The registration ledger. Raw OS tokens never leave the backend, so this is address + who/where/
+ *  when only. --forget drops a dead row (rotated token, wrong project) that would otherwise sit
+ *  here forever and fail every send. */
+const devices = defineCommand({
+  name: "devices",
+  aliases: ["device"],
+  summary: "List the devices that registered for this project (the 'why didn't it arrive?' command)",
+  description: "A device appears here after the app calls Push.register(). `lecodes dev` bundles are unattributed — register() rejects there; open a PUBLISHED project via QR.",
+  flags: {
+    user: str("only that user's devices", { alias: "u", value: "<id>" }),
+    forget: str("drop a dead registration", { value: "<pa_…>" }),
+    ...confirmFlag,
+  },
+  examples: ["lecodes pn devices", "lecodes pn devices --user u42", "lecodes pn devices --forget pa_abc -y"],
+  run: async ({ flags }) => {
+    const { apiUrl, token, manifest } = linkedProject()
+    const user = flags.user
+
+    if (flags.forget) {
+      if (!flags.yes) {
+        warn(`Forgetting ${c.bold(flags.forget)} — sends to this address stop immediately. The device gets a NEW address on its next Push.register().`)
+        if (!await confirm("Forget it?")) return info("Cancelled.")
+      }
+      await forgetPushDevice(apiUrl, token, manifest.uuid, flags.forget)
+      success(`Forgot ${c.bold(flags.forget)}.`)
+      return
     }
-    await forgetPushDevice(ctx.apiUrl, ctx.token, ctx.uuid, forget)
-    success(`Forgot ${c.bold(forget)}.`)
-    return
-  }
 
-  const { devices, truncated } = await listPushDevices(ctx.apiUrl, ctx.token, ctx.uuid, user)
+    const { devices, truncated } = await listPushDevices(apiUrl, token, manifest.uuid, user)
 
-  if (devices.length === 0) {
-    info(user
-      ? `No devices registered for user ${c.bold(user)} in ${c.bold(ctx.name)}.`
-      : `No devices registered in ${c.bold(ctx.name)} yet.`)
-    info(c.dim("A device appears here after the app calls Push.register(). Note that `lecodes dev`"))
-    info(c.dim("bundles are unattributed — register() rejects there; open a PUBLISHED project via QR."))
-    return
-  }
+    if (devices.length === 0) {
+      info(user
+        ? `No devices registered for user ${c.bold(user)} in ${c.bold(manifest.name)}.`
+        : `No devices registered in ${c.bold(manifest.name)} yet.`)
+      info(c.dim("A device appears here after the app calls Push.register(). Note that `lecodes dev`"))
+      info(c.dim("bundles are unattributed — register() rejects there; open a PUBLISHED project via QR."))
+      return
+    }
 
-  info(`${devices.length} device${devices.length === 1 ? "" : "s"} in ${c.bold(ctx.name)}${user ? ` for user ${c.bold(user)}` : ""}:`)
-  table([
-    [c.dim("ADDRESS"), c.dim("PLATFORM"), c.dim("USER"), c.dim("HOST"), c.dim("LAST SEEN")],
-    ...devices.map(device => [
-      device.disabledAt ? c.dim(device.address) : device.address,
-      deviceLabel(device),
-      device.user ?? c.dim("—"),
-      device.hostApp,
-      device.disabledAt ? c.red("disabled") : ago(device.lastSeenAt),
-    ]),
-  ])
-  if (devices.some(d => d.disabledAt)) {
-    info(c.dim("Disabled = the provider reported a dead token; re-registering from the device revives it."))
-  }
-  if (truncated) warn("Showing the 200 most recently seen — there are more.")
-}
+    info(`${devices.length} device${devices.length === 1 ? "" : "s"} in ${c.bold(manifest.name)}${user ? ` for user ${c.bold(user)}` : ""}:`)
+    table([
+      [c.dim("ADDRESS"), c.dim("PLATFORM"), c.dim("USER"), c.dim("HOST"), c.dim("LAST SEEN")],
+      ...devices.map(device => [
+        device.disabledAt ? c.dim(device.address) : device.address,
+        deviceLabel(device),
+        device.user ?? c.dim("—"),
+        device.hostApp,
+        device.disabledAt ? c.red("disabled") : relativeTime(device.lastSeenAt),
+      ]),
+    ])
+    if (devices.some(d => d.disabledAt)) {
+      info(c.dim("Disabled = the provider reported a dead token; re-registering from the device revives it."))
+    }
+    if (truncated) warn("Showing the 200 most recently seen — there are more.")
+  },
+})
 
 /* ---------------------------------------- keys ---------------------------------------- */
 
-const pnKeysList = async (ctx: Context) => {
-  const keys = await listPushKeys(ctx.apiUrl, ctx.token, ctx.uuid)
+const listKeys = async ({ apiUrl, token, manifest }: LinkedProject): Promise<void> => {
+  const keys = await listPushKeys(apiUrl, token, manifest.uuid)
   if (keys.length === 0) {
-    info(`No push keys in ${c.bold(ctx.name)}.`)
+    info(`No push keys in ${c.bold(manifest.name)}.`)
     info(c.dim("You only need one to send from your OWN server — `lecodes pn send` uses your login."))
     info(c.dim("Mint one with `lecodes pn keys new \"prod server\" --env`."))
     return
   }
-  info(`${keys.length} push key${keys.length === 1 ? "" : "s"} in ${c.bold(ctx.name)}:`)
+  info(`${keys.length} push key${keys.length === 1 ? "" : "s"} in ${c.bold(manifest.name)}:`)
   table([
     [c.dim("ID"), c.dim("NAME"), c.dim("KEY"), c.dim("LAST USED")],
-    ...keys.map(key => [String(key.id), key.name, `${key.prefix}${c.dim("…")}`, ago(key.lastUsedAt)]),
+    ...keys.map(key => [String(key.id), key.name, `${key.prefix}${c.dim("…")}`, relativeTime(key.lastUsedAt)]),
   ])
 }
 
-/** Append `LECODES_PUSH_KEY=…` to <root>/.env and make sure git can't swallow it. Returns the
- *  paths touched. A key already in .env is REPLACED — rotating shouldn't leave two live lines. */
-const writeEnv = (root: string, key: string): string[] => {
-  const touched: string[] = []
-  const envPath = join(root, ".env")
-  const line = `${ENV_VAR}=${key}`
-
-  const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : ""
-  if (new RegExp(`^${ENV_VAR}=`, "m").test(existing)) {
-    writeFileSync(envPath, existing.replace(new RegExp(`^${ENV_VAR}=.*$`, "m"), line))
-  } else {
-    const separator = !existing || existing.endsWith("\n") ? "" : "\n"
-    appendFileSync(envPath, `${separator}${line}\n`)
-  }
-  touched.push(".env")
-
-  // A push key in a committed .env is the one way this command could make things worse.
-  const ignorePath = join(root, ".gitignore")
-  const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : ""
-  if (!ignore.split("\n").some(l => l.trim() === ".env")) {
-    const separator = !ignore || ignore.endsWith("\n") ? "" : "\n"
-    appendFileSync(ignorePath, `${separator}.env\n`)
-    touched.push(".gitignore")
-  }
-  return touched
-}
-
-/** `lecodes pn keys new [name] [--env]` — the server mints it; this is the ONLY time the
- *  plaintext exists anywhere, so print it loudly (or bank it in .env with --env). */
-const pnKeysNew = async (ctx: Context, args: Args) => {
-  const name = args._[2] ?? flagStr(args, "name")
-  const created = await createPushKey(ctx.apiUrl, ctx.token, ctx.uuid, name)
-
-  success(`Created push key ${c.bold(created.name)} (id ${created.id}).`)
-  log()
-  log(`  ${c.bold(created.key)}`)
-  log()
-
-  if (flagBool(args, "env")) {
-    const touched = writeEnv(ctx.root, created.key)
-    success(`Wrote ${ENV_VAR} to ${touched.join(" + ")}.`)
-  } else {
-    warn("Copy it now — it is never shown again. Lose it and you mint a new one.")
-    info(c.dim(`  Tip: \`lecodes pn keys new --env\` writes it straight into .env as ${ENV_VAR}.`))
-  }
-
-  log()
-  info(c.dim("Send from your server with:"))
-  log(c.dim(`  curl -X POST ${ctx.apiUrl}/api/projects/${ctx.uuid}/push/send \\`))
-  log(c.dim(`    -H "Authorization: Bearer $${ENV_VAR}" -H "Content-Type: application/json" \\`))
-  log(c.dim(`    -d '{"title":"Order shipped","users":["u42"]}'`))
-}
-
-/** `lecodes pn keys revoke <id>` — deletion, effective on the next request. Confirmed unless -y. */
-const pnKeysRevoke = async (ctx: Context, args: Args) => {
-  const raw = args._[2]
-  if (!raw) throw new CliError("Which key? `lecodes pn keys` lists their ids, then `lecodes pn keys revoke <id>`.")
-  const id = Number(raw)
-  if (!Number.isInteger(id)) throw new CliError(`"${raw}" is not a key id — run \`lecodes pn keys\` to see them.`)
-
-  const keys = await listPushKeys(ctx.apiUrl, ctx.token, ctx.uuid)
-  const key = keys.find(k => k.id === id)
-  if (!key) throw new CliError(`No push key with id ${id} in ${ctx.name}.`)
-
-  if (!flagBool(args, "yes", "y")) {
-    warn(`Revoking ${c.bold(key.name)} (${key.prefix}…) — any server still using it stops sending immediately.`)
-    if (!await confirm("Revoke it?")) return info("Cancelled.")
-  }
-  await revokePushKey(ctx.apiUrl, ctx.token, ctx.uuid, id)
-  success(`Revoked push key ${c.bold(key.name)}.`)
-}
+/** The server mints it; this is the ONLY time the plaintext exists anywhere, so print it loudly
+ *  (or bank it in .env with --env — replacing a previous line, since rotating shouldn't leave two
+ *  live keys — and make sure git can't swallow it). */
+const keysNew = defineCommand({
+  name: "new",
+  aliases: ["create"],
+  summary: "Mint a push key for YOUR server (owner only; shown once)",
+  usage: "[name]",
+  description: "A push key is generated BY the server — you can't choose or recover one. It only sends for this project, which is why deploying it beats deploying a personal access token.",
+  flags: {
+    name: str("the key's name (or the first positional)", { value: "<s>" }),
+    env: bool(`write it to .env as ${ENV_VAR} (+ gitignore)`),
+  },
+  examples: ['lecodes pn keys new "prod server" --env'],
+  run: async ({ args, flags }) => {
+    const { root, apiUrl, token, manifest } = linkedProject()
+    const created = await createPushKey(apiUrl, token, manifest.uuid, args[0] ?? flags.name)
+
+    success(`Created push key ${c.bold(created.name)} (id ${created.id}).`)
+    log()
+    log(`  ${c.bold(created.key)}`)
+    log()
+
+    if (flags.env) {
+      const touched = upsertDotEnv(root, { [ENV_VAR]: created.key })
+      success(`Wrote ${ENV_VAR} to ${touched.join(" + ")}.`)
+    } else {
+      warn("Copy it now — it is never shown again. Lose it and you mint a new one.")
+      info(c.dim(`  Tip: \`lecodes pn keys new --env\` writes it straight into .env as ${ENV_VAR}.`))
+    }
 
-const pnKeys = async (args: Args) => {
-  const ctx = context()
-  const sub = args._[1]
-  if (!sub || sub === "list") return pnKeysList(ctx)
-  if (sub === "new" || sub === "create") return pnKeysNew(ctx, args)
-  if (sub === "revoke" || sub === "delete" || sub === "rm") return pnKeysRevoke(ctx, args)
-  throw new CliError(`Unknown keys command "${sub}" — use: lecodes pn keys [list | new [name] | revoke <id>]`)
-}
+    log()
+    info(c.dim("Send from your server with:"))
+    log(c.dim(`  curl -X POST ${apiUrl}/api/projects/${manifest.uuid}/push/send \\`))
+    log(c.dim(`    -H "Authorization: Bearer $${ENV_VAR}" -H "Content-Type: application/json" \\`))
+    log(c.dim(`    -d '{"title":"Order shipped","users":["u42"]}'`))
+  },
+})
+
+/** Deletion, effective on the next request. Confirmed unless -y. */
+const keysRevoke = defineCommand({
+  name: "revoke",
+  aliases: ["delete", "rm"],
+  summary: "Revoke a key — any server still using it stops sending immediately",
+  usage: "<id>",
+  flags: confirmFlag,
+  examples: ["lecodes pn keys revoke 3 -y"],
+  run: async ({ args, flags }) => {
+    const { apiUrl, token, manifest } = linkedProject()
+    const raw = args[0]
+    if (!raw) throw new UsageError("Which key? `lecodes pn keys` lists their ids, then `lecodes pn keys revoke <id>`.")
+    const id = Number(raw)
+    if (!Number.isInteger(id)) throw new CliError(`"${raw}" is not a key id — run \`lecodes pn keys\` to see them.`)
+
+    const keys = await listPushKeys(apiUrl, token, manifest.uuid)
+    const key = keys.find(k => k.id === id)
+    if (!key) throw new CliError(`No push key with id ${id} in ${manifest.name}.`)
+
+    if (!flags.yes) {
+      warn(`Revoking ${c.bold(key.name)} (${key.prefix}…) — any server still using it stops sending immediately.`)
+      if (!await confirm("Revoke it?")) return info("Cancelled.")
+    }
+    await revokePushKey(apiUrl, token, manifest.uuid, id)
+    success(`Revoked push key ${c.bold(key.name)}.`)
+  },
+})
+
+const keys = defineCommand({
+  name: "keys",
+  aliases: ["key"],
+  summary: "Push keys for YOUR server: list (bare), mint, revoke",
+  description: "Bare `lecodes pn keys` lists this project's keys. You only need one to send from your OWN server — `lecodes pn send` uses your login.",
+  commands: [keysNew, keysRevoke],
+  examples: ["lecodes pn keys", 'lecodes pn keys new "prod server" --env', "lecodes pn keys revoke 3"],
+  run: () => listKeys(linkedProject()),
+})
 
 /* --------------------------------------- entry ---------------------------------------- */
 
-const PN_HELP = `${c.bold("lecodes pn")} — push notifications for this project.
-
-${c.bold("Commands:")}
-  pn send --title <s>           Send a notification (uses your login — no key needed)
-                                  --body <s>      second line
-                                  --url <s>       deep link (also arrives as app.launchUrl)
-                                  --user <ids>    target Push.register({ user }) ids, comma-separated
-                                  --to <pa_…>     target addresses, comma-separated
-                                  --badge <n>     app icon badge
-                                  --data <json>   your JSON payload (≤ 2 KB)
-  pn devices                    List the devices that registered for this project
-                                  --user <id>     only that user's devices
-                                  --forget <pa_…> drop a dead registration (-y to skip confirm)
-  pn keys                       List this project's push keys
-  pn keys new [name]            Mint one for YOUR server (owner only; shown once)
-                                  --env           write it to .env as ${ENV_VAR} (+ gitignore)
-  pn keys revoke <id>           Revoke a key (-y to skip the confirmation)
-
-${c.dim("A push key is generated BY the server — you can't choose or recover one. It only sends")}
-${c.dim("for this project, which is why deploying it beats deploying a personal access token.")}`
-
-export const pn = async (args: Args) => {
-  const sub = args._[0]
-  if (!sub || sub === "help") return log(PN_HELP)
-  if (sub === "send") return pnSend(args)
-  if (sub === "devices" || sub === "device") return pnDevices(args)
-  if (sub === "keys" || sub === "key") return pnKeys(args)
-  throw new CliError(`Unknown pn command "${sub}" — use: lecodes pn <send | devices | keys>. Run \`lecodes pn\` for the full list.`)
-}
+export default defineCommand({
+  name: "pn",
+  summary: "Push notifications: send | devices | keys",
+  description: "Push notifications for the project in .lecodes/manifest.json. `send` uses your login (no push key needed to test); `devices` is the registration ledger; `keys` mints the `lecodes_pk_…` keys a production server deploys.",
+  commands: [send, devices, keys],
+})

package/src/commands/pull.ts

@@ -1,69 +1,65 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs"
 import { dirname, join } from "node:path"
-import { downloadBlob, getCommits, getProject, type Project, type ProjectAsset } from "../api"
-import { loadConfig, requireApiUrl, requireToken } from "../config"
-import { findProjectRoot, readManifest, writeManifest, type FileKind } from "../manifest"
-import { buildPaths, materializeAssets } from "../project"
-import { materializeTypes, writeTsconfig } from "../types"
-import { diffLocal, hasChanges, scanProject } from "../localFiles"
-import { CliError, c, info, success, progress, endProgress, flagBool, sha256, toKey, type Args } from "../util"
+import { CliError, bool, c, defineCommand, endProgress, info, progress, success } from "../cli"
+import { downloadBlob, getCommits, getProject, type Project, type ProjectAsset } from "../platform/api"
+import { diffLocal, hasChanges, scanProject } from "../project/localFiles"
+import { writeManifest, type FileKind, type Manifest } from "../project/manifest"
+import { buildPaths, materializeAssets } from "../project/materialize"
+import { sha256, toKey } from "../project/paths"
+import { materializeTypes, writeTsconfig } from "../project/types"
+import { linkedProject } from "./shared"
 
 /* `lecodes pull` — overwrite local files with the project's current remote state. Refuses to
  * clobber uncommitted local edits unless --force. Given file/folder paths, pulls only those (a
  * targeted "take the server's version of this file" for manual conflict resolution). */
-export const pull = async (args: Args) => {
-  const root = findProjectRoot(process.cwd())
-  const manifest = readManifest(root)
-  const config = loadConfig()
-  const apiUrl = requireApiUrl(config)
-  const token = requireToken(config)
+export default defineCommand({
+  name: "pull",
+  summary: "Overwrite local files with the project's current server state",
+  usage: "[path…]",
+  description: "With paths: pull only those files / folders and keep every other local edit (no dirty check; you still owe a full pull or --force before a clean push).",
+  flags: {
+    force: bool("discard uncommitted local changes"),
+    "no-types": bool("skip the .d.ts / tsconfig refresh"),
+  },
+  run: async ({ args, flags }) => {
+    const { root, manifest, apiUrl, token } = linkedProject()
 
-  // Targeted pull of specific paths — no dirty guard (the point is to merge into local edits) and
-  // baseHeadId is left as-is (you still owe a full pull/--force before a clean push).
-  if (args._.length > 0) {
-    const project = await getProject(apiUrl, token, manifest.uuid)
-    await pullPaths(root, manifest, project, args._.map(toKey), apiUrl, token)
-    return
-  }
-
-  if (!flagBool(args, "force") && hasChanges(diffLocal(manifest, scanProject(root, manifest)))) {
-    throw new CliError("You have local changes. Push them first, or run `lecodes pull --force` to discard them.")
-  }
+    if (args.length > 0) {
+      const project = await getProject(apiUrl, token, manifest.uuid)
+      await pullPaths(root, manifest, project, args.map(toKey), apiUrl, token)
+      return
+    }
+    if (!flags.force && hasChanges(diffLocal(manifest, scanProject(root, manifest)))) {
+      throw new CliError("You have local changes. Push them first, or run `lecodes pull --force` to discard them.")
+    }
 
-  info(c.dim("Fetching project…"))
-  const project = await getProject(apiUrl, token, manifest.uuid)
+    info(c.dim("Fetching project…"))
+    const project = await getProject(apiUrl, token, manifest.uuid)
 
-  // Remove tracked files that no longer exist remotely (untracked local files are left alone).
-  const remotePaths = new Set([...buildPaths(project.assets).entries()]
-    .filter(([id]) => project.assets.find(a => a.id === id)?.type !== "folder")
-    .map(([, path]) => path))
-  for (const path of Object.keys(manifest.files)) {
-    if (!remotePaths.has(path)) {
+    // Remove tracked files that no longer exist remotely (untracked local files are left alone).
+    const remotePaths = new Set([...buildPaths(project.assets).entries()]
+      .filter(([id]) => project.assets.find(a => a.id === id)?.type !== "folder")
+      .map(([, path]) => path))
+    for (const path of Object.keys(manifest.files)) {
+      if (remotePaths.has(path)) continue
       const abs = join(root, ...path.replace(/^\//, "").split("/"))
       if (existsSync(abs)) rmSync(abs)
     }
-  }
-
-  const files = await materializeAssets(root, project, apiUrl, token, progress)
-  endProgress()
-  if (!flagBool(args, "no-types")) {
-    await materializeTypes(root, apiUrl)
-    writeTsconfig(root)
-  }
 
-  const commits = await getCommits(apiUrl, token, manifest.uuid)
-  writeManifest(root, { ...manifest, name: project.name, baseHeadId: commits.headId, files })
+    const files = await materializeAssets(root, project, apiUrl, token, progress)
+    endProgress()
+    if (!flags["no-types"]) { await materializeTypes(root, apiUrl); writeTsconfig(root) }
 
-  success(`Pulled latest into ${c.bold(manifest.name)}.`)
-}
+    const commits = await getCommits(apiUrl, token, manifest.uuid)
+    writeManifest(root, { ...manifest, name: project.name, baseHeadId: commits.headId, files })
+    success(`Pulled latest into ${c.bold(manifest.name)}.`)
+  },
+})
 
 const kindOf = (type: ProjectAsset["type"]): FileKind => (type === "file" ? "resource" : type as FileKind)
 
 /** Pull only the given paths (a file, or every file under a folder) from the server, in place. */
-const pullPaths = async (
-  root: string, manifest: ReturnType<typeof readManifest>, project: Project,
-  paths: string[], apiUrl: string, token: string,
-) => {
+const pullPaths = async (root: string, manifest: Manifest, project: Project, paths: string[], apiUrl: string, token: string): Promise<void> => {
   const pathById = buildPaths(project.assets)
   const byPath = new Map<string, ProjectAsset>()
   for (const asset of project.assets) byPath.set(pathById.get(asset.id)!, asset)
@@ -73,14 +69,11 @@ const pullPaths = async (
   for (const path of paths) {
     const asset = byPath.get(path)
     if (!asset) throw new CliError(`Not found on the server: ${path}`)
-    if (asset.type === "folder") {
-      const prefix = path + "/"
-      const under = project.assets.filter(a => a.type !== "folder" && pathById.get(a.id)!.startsWith(prefix))
-      if (under.length === 0) throw new CliError(`Folder is empty on the server: ${path}`)
-      targets.push(...under)
-    } else {
-      targets.push(asset)
-    }
+    if (asset.type !== "folder") { targets.push(asset); continue }
+    const prefix = path + "/"
+    const under = project.assets.filter(a => a.type !== "folder" && pathById.get(a.id)!.startsWith(prefix))
+    if (under.length === 0) throw new CliError(`Folder is empty on the server: ${path}`)
+    targets.push(...under)
   }
 
   const files = { ...manifest.files }