uniweb 0.12.21 → 0.12.22

package/src/utils/placement.js

@@ -0,0 +1,100 @@
+/**
+ * Package placement resolution — shared by `add` and `clone`.
+ *
+ * Kept dependency-free (no `@uniweb/build`, no fs) on purpose: `clone` imports
+ * it and must run from a global install before any project — anything that
+ * statically pulls in `@uniweb/build` would crash `npx uniweb@latest clone`
+ * (the same reason `utils/workspace.js` loads the classifier lazily).
+ */
+
+/** Foundation placement defaults (folder `src/`, package `src`). */
+export const FOUNDATION_KIND = { defaultDir: 'src', defaultPkg: 'src', projectSub: 'src' }
+
+/** Site placement defaults (folder `site/`, package `site`). */
+export const SITE_KIND = { defaultDir: 'site', defaultPkg: 'site', projectSub: 'site' }
+
+/**
+ * Resolve where a foundation or site should be placed, given the user's input.
+ *
+ * The rule: **the user names a folder, and we create exactly that folder.**
+ * No silent nesting under `foundations/` / `sites/`, no inferring layout from
+ * pre-existing globs. The framework doesn't require any particular folder
+ * structure (the build classifies packages by their contents, not their
+ * location), so the CLI shouldn't impose one.
+ *
+ * Resolution priority (foundation example, same shape for site):
+ *
+ *   1. `--path <dir>`                   → explicit folder. Name is the path's
+ *                                          last segment (used as the package
+ *                                          name unless `name` was also given).
+ *   2. `name` contains `/`              → treat as a path (e.g., `foundations/ui`).
+ *                                          Folder = the path, package name =
+ *                                          the last segment.
+ *   3. `name` (no slash)                → folder = `<name>/`, package name = `<name>`.
+ *   4. `--project <project>`            → folder = `<project>/<defaultSub>` and
+ *                                          package name = `<project>-<defaultSub>`
+ *                                          (the co-located convention; only this
+ *                                          one uses the `-src` / `-site` suffix).
+ *   5. (no input)                       → folder = `<defaultDir>/`, package name
+ *                                          = `<defaultPkg>` (`src/` + `src`
+ *                                          for foundations; `site/` + `site` for
+ *                                          sites).
+ *
+ * @param {string} rootDir
+ * @param {string|null} name - Either a bare name or a path-with-slash.
+ * @param {{ path?: string, project?: string }} opts
+ * @param {{ defaultDir: string, defaultPkg: string, projectSub: string }} kind
+ * @returns {{ relativePath: string, packageName: string }}
+ */
+export function resolvePlacement(rootDir, name, opts, kind) {
+  // 1. --path is a PARENT directory. The folder is `<path>/<name>` if a
+  //    name was given, or `<path>` itself if not (the path's last segment
+  //    is then taken as the package name).
+  if (opts.path) {
+    const parent = opts.path.replace(/\/+$/, '')
+    if (name) {
+      const last = name.split('/').filter(Boolean).pop()
+      return {
+        relativePath: `${parent}/${name}`.replace(/\/+/g, '/'),
+        packageName: last,
+      }
+    }
+    const lastSegment = parent.split('/').filter(Boolean).pop() || parent
+    return {
+      relativePath: parent,
+      packageName: lastSegment,
+    }
+  }
+
+  // 2. name contains a slash → treat as a path.
+  if (name && name.includes('/')) {
+    const relativePath = name.replace(/\/+$/, '')
+    const lastSegment = relativePath.split('/').filter(Boolean).pop()
+    return {
+      relativePath,
+      packageName: lastSegment,
+    }
+  }
+
+  // 3. Bare name.
+  if (name) {
+    return {
+      relativePath: name,
+      packageName: name,
+    }
+  }
+
+  // 4. --project (co-located convention with -src / -site suffix).
+  if (opts.project) {
+    return {
+      relativePath: `${opts.project}/${kind.projectSub}`,
+      packageName: `${opts.project}-${kind.projectSub}`,
+    }
+  }
+
+  // 5. Default placement.
+  return {
+    relativePath: kind.defaultDir,
+    packageName: kind.defaultPkg,
+  }
+}

package/src/utils/registry-auth.js

@@ -0,0 +1,380 @@
+/**
+ * Registry (new-backend) credential storage + login.
+ *
+ * SEPARATE from utils/auth.js on purpose. That module is the LEGACY platform
+ * auth — browser/social login via `cli-auth.php`, a JWT shared by `publish`
+ * and `deploy`, stored in ~/.uniweb/auth.json. This module serves the NEW
+ * backend that `uniweb register` talks to:
+ *
+ *   - non-browser username/password login → POST {apiBase}/dev/auth/login
+ *   - the returned bearer is an OPAQUE random token (NOT a JWT — never decode it,
+ *     it carries no claims; org memberships come from a separate authed read)
+ *   - stored in a register-scoped slot (~/.uniweb/registry-auth.json) so it can
+ *     never clobber the legacy token publish/deploy rely on.
+ *
+ * Token resolution for `register` (the `--token` flag is handled by the caller,
+ * ahead of this): UNIWEB_TOKEN env > stored session (unexpired) >
+ * UNIWEB_USERNAME/UNIWEB_PASSWORD env (non-interactive) > interactive prompt.
+ *
+ * Login response shape (agreed with backend, 2026-05-26):
+ *   { token, expires_at, account: { uuid, username, handle } }
+ *   token + expiry top-level; identity nested under `account` (handle nullable).
+ */
+
+import { existsSync } from 'node:fs'
+import { readFile, writeFile, mkdir, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { createServer } from 'node:http'
+import { randomBytes } from 'node:crypto'
+import { getAuthDir, isExpired } from './auth.js'
+
+const LOGIN_PATH = '/dev/auth/login'
+
+/**
+ * Path to the register-scoped credential file (~/.uniweb/registry-auth.json).
+ * Reuses the legacy auth dir (the ~/.uniweb home is shared infrastructure);
+ * only the filename differs, keeping the two tokens in separate slots.
+ * @returns {string}
+ */
+export function getRegistryAuthPath() {
+  return join(getAuthDir(), 'registry-auth.json')
+}
+
+/**
+ * Read the stored registry session, or null. No JWT backfill — the token is
+ * opaque, so there are no claims to decode (unlike legacy readAuth()).
+ * @returns {Promise<{ token: string, expiresAt?: string, accountId?: number, sessionId?: number, username?: string, handle?: string, uuid?: string } | null>}
+ */
+export async function readRegistryAuth() {
+  const path = getRegistryAuthPath()
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Persist the registry session record.
+ * @param {Object} record
+ */
+export async function writeRegistryAuth(record) {
+  await mkdir(getAuthDir(), { recursive: true })
+  await writeFile(getRegistryAuthPath(), JSON.stringify(record, null, 2))
+}
+
+/**
+ * Remove the stored registry session.
+ */
+export async function clearRegistryAuth() {
+  const path = getRegistryAuthPath()
+  if (existsSync(path)) await unlink(path)
+}
+
+/**
+ * Username/password login against the new backend. POSTs to
+ * `{apiBase}/dev/auth/login`, reads the opaque token from the JSON body
+ * (the HttpOnly cookie the response also sets is ignored on the CLI), and
+ * persists it. Throws on non-2xx or a tokenless body.
+ *
+ * @param {Object} params
+ * @param {string} params.apiBase - new-backend origin, e.g. http://localhost:8080
+ * @param {string} params.username
+ * @param {string} params.password
+ * @returns {Promise<Object>} the stored session record (incl. `token`)
+ */
+export async function loginToRegistry({ apiBase, username, password } = {}) {
+  if (!apiBase) throw new Error('loginToRegistry: apiBase is required')
+  const url = `${apiBase.replace(/\/$/, '')}${LOGIN_PATH}`
+
+  let res
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username, password }),
+    })
+  } catch (err) {
+    throw new Error(`Could not reach the login endpoint at ${url}: ${err.message}`)
+  }
+
+  if (!res.ok) {
+    let detail = ''
+    try { detail = (await res.text()).slice(0, 300) } catch { /* ignore */ }
+    const e = new Error(`Login failed: HTTP ${res.status} ${res.statusText}${detail ? ` — ${detail}` : ''}`)
+    e.status = res.status
+    throw e
+  }
+
+  const data = await res.json().catch(() => null)
+  if (!data?.token) throw new Error('Login succeeded but the response carried no token.')
+
+  // New-backend login body (agreed with backend, 2026-05-26):
+  //   { token, expires_at, account: { uuid, username, handle } }
+  // token/expires_at stay top-level; identity is nested under `account`. The
+  // token is opaque (no claims), and `expires_at` is stored as `expiresAt` so
+  // the shared isExpired() works unchanged. Tolerant of the pre-#2 flat body
+  // (no `account` key) — token + expiry still resolve, identity is just skipped.
+  const account = data.account || {}
+  const record = { token: data.token }
+  if (data.expires_at) record.expiresAt = data.expires_at
+  if (account.uuid) record.uuid = account.uuid
+  if (account.username) record.username = account.username
+  if (account.handle) record.handle = account.handle
+
+  await writeRegistryAuth(record)
+  return record
+}
+
+/**
+ * Ensure a usable new-backend bearer for `register`. Resolution order:
+ *   UNIWEB_TOKEN env > stored unexpired session > UNIWEB_USERNAME/PASSWORD env
+ *   (non-interactive) > interactive username/password prompt.
+ *
+ * In non-interactive mode with no token/env creds, bails with an actionable
+ * error instead of hanging on a prompt (mirrors ensureAuth's CI guard).
+ *
+ * @param {Object} options
+ * @param {string} options.apiBase - new-backend origin (e.g. http://localhost:8080)
+ * @param {string} [options.command] - command needing auth (for messaging)
+ * @param {string[]} [options.args] - argv slice; checked for --non-interactive
+ * @returns {Promise<string>} bearer token
+ */
+export async function ensureRegistryAuth({ apiBase, command = 'This command', args = [] } = {}) {
+  if (process.env.UNIWEB_TOKEN) return process.env.UNIWEB_TOKEN
+
+  const stored = await readRegistryAuth()
+  if (stored?.token && !isExpired(stored)) return stored.token
+
+  // Non-interactive login from env (CI / agents) before any prompt.
+  const envUser = process.env.UNIWEB_USERNAME
+  const envPass = process.env.UNIWEB_PASSWORD
+  if (envUser && envPass) {
+    const record = await loginToRegistry({ apiBase, username: envUser, password: envPass })
+    return record.token
+  }
+
+  const { isNonInteractive, getCliPrefix } = await import('./interactive.js')
+  if (isNonInteractive(args)) {
+    const prefix = getCliPrefix()
+    const reason = stored && isExpired(stored) ? 'Session expired.' : 'Not logged in.'
+    console.error(`\x1b[31m✗\x1b[0m ${reason} ${command} requires a Uniweb account, and the CLI is non-interactive (CI / no TTY / --non-interactive).`)
+    console.error('  Options:')
+    console.error(`    • Set UNIWEB_TOKEN to a bearer token.`)
+    console.error(`    • Set UNIWEB_USERNAME + UNIWEB_PASSWORD to log in non-interactively.`)
+    console.error(`    • Run \`${prefix} login\` interactively first, then re-run.`)
+    process.exit(1)
+  }
+
+  if (stored && isExpired(stored)) {
+    console.log(`\x1b[33mSession expired.\x1b[0m ${command} requires a Uniweb account.\n`)
+  } else {
+    console.log(`${command} requires a Uniweb account.\n`)
+  }
+
+  // Interactive: hand off to the multi-method login picker, reuse its session.
+  const record = await runRegistryLogin({ apiBase, args })
+  if (!record?.token) process.exit(1)
+  return record.token
+}
+
+// The browser/OAuth flow is wired below (loginViaBrowser: a loopback redirect
+// against the backend's /dev/auth/cli/authorize, token-in-redirect). Kept
+// gated until that endpoint is live on the backend — flip to true then, and the
+// picker offers Browser/social as the default (and `--browser` works).
+const BROWSER_AVAILABLE = false
+
+/**
+ * GET /dev/auth/me with a bearer → the account object ({ uuid, username,
+ * handle }), or throws. Used to verify + identify a pasted token.
+ */
+export async function fetchMe({ apiBase, token }) {
+  const res = await fetch(`${apiBase.replace(/\/$/, '')}/dev/auth/me`, {
+    headers: { Authorization: `Bearer ${token}` },
+  })
+  if (!res.ok) {
+    const e = new Error(`token check failed: HTTP ${res.status} ${res.statusText}`)
+    e.status = res.status
+    throw e
+  }
+  const data = await res.json().catch(() => null)
+  return data?.account || null
+}
+
+// Username/password — prompts unless UNIWEB_USERNAME/PASSWORD are set.
+async function loginViaPassword({ apiBase, nonInteractive }) {
+  let username = process.env.UNIWEB_USERNAME
+  let password = process.env.UNIWEB_PASSWORD
+  if (!username || !password) {
+    if (nonInteractive) {
+      throw new Error('username/password login needs a terminal — set UNIWEB_USERNAME + UNIWEB_PASSWORD (or UNIWEB_TOKEN).')
+    }
+    const prompts = (await import('prompts')).default
+    const resp = await prompts([
+      { type: 'text', name: 'username', message: 'Username:', validate: (v) => (v ? true : 'Username is required') },
+      { type: 'password', name: 'password', message: 'Password:', validate: (v) => (v ? true : 'Password is required') },
+    ], { onCancel: () => { console.log('\nLogin cancelled.'); process.exit(0) } })
+    username = resp.username
+    password = resp.password
+    if (!username || !password) process.exit(1)
+  }
+  return loginToRegistry({ apiBase, username, password })
+}
+
+// Paste a token — verified + identified via /me before it's stored.
+async function loginViaTokenPaste({ apiBase, nonInteractive }) {
+  if (nonInteractive) {
+    throw new Error('token paste needs a terminal — set UNIWEB_TOKEN instead.')
+  }
+  const prompts = (await import('prompts')).default
+  const { token } = await prompts({
+    type: 'password', name: 'token', message: 'Paste your token:', validate: (v) => (v ? true : 'Token is required'),
+  }, { onCancel: () => { console.log('\nLogin cancelled.'); process.exit(0) } })
+  if (!token) process.exit(1)
+  const account = await fetchMe({ apiBase, token }) // throws if the token is invalid
+  const record = { token }
+  if (account?.uuid) record.uuid = account.uuid
+  if (account?.username) record.username = account.username
+  if (account?.handle) record.handle = account.handle
+  await writeRegistryAuth(record)
+  return record
+}
+
+// Open a URL in the default browser. Returns whether it launched.
+async function openBrowser(url) {
+  try {
+    const { exec } = await import('node:child_process')
+    const cmd = process.platform === 'darwin' ? `open "${url}"`
+      : process.platform === 'win32' ? `start "" "${url}"`
+        : `xdg-open "${url}"`
+    return await new Promise((resolve) => exec(cmd, (err) => resolve(!err)))
+  } catch {
+    return false
+  }
+}
+
+// Browser / social — loopback OAuth against the backend's /cli/authorize.
+// The CLI hosts a one-shot 127.0.0.1 server, opens the browser to authorize, and
+// the backend (after the Google dance) 302s back to the loopback with the token
+// (or an error). state is a CSRF nonce echoed back and verified. The token never
+// leaves browser→localhost. Gated by BROWSER_AVAILABLE until the endpoint is live.
+async function loginViaBrowser({ apiBase }) {
+  if (!BROWSER_AVAILABLE) {
+    throw new Error('browser/social login for the new backend isn’t available yet — use --password or --token-paste.')
+  }
+  const base = apiBase.replace(/\/$/, '')
+  const state = randomBytes(16).toString('hex')
+
+  const result = await new Promise((resolve) => {
+    const server = createServer((req, res) => {
+      const u = new URL(req.url, 'http://127.0.0.1')
+      if (u.pathname !== '/callback') { res.writeHead(404); res.end('Not found'); return }
+      const token = u.searchParams.get('token')
+      const error = u.searchParams.get('error')
+      const gotState = u.searchParams.get('state')
+      const failed = !!error || !token || gotState !== state
+      res.writeHead(failed ? 400 : 200, { 'Content-Type': 'text/html' })
+      res.end(`<!doctype html><html><body style="font-family:system-ui,sans-serif;text-align:center;padding:60px">`
+        + `<h2 style="color:${failed ? '#dc2626' : '#16a34a'}">${failed ? 'Login failed' : 'Login successful'}</h2>`
+        + `<p>You can close this tab and return to your terminal.</p></body></html>`)
+      cleanup()
+      if (error) resolve({ error })
+      else if (gotState !== state) resolve({ error: 'state mismatch — please try again.' })
+      else if (!token) resolve({ error: 'no token returned by the callback.' })
+      else resolve({ token })
+    })
+    let timer
+    function cleanup() { clearTimeout(timer); server.close() }
+    server.on('error', (e) => resolve({ error: `loopback server error: ${e.message}` }))
+    server.listen(0, '127.0.0.1', async () => {
+      const { port } = server.address()
+      const redirectUri = `http://127.0.0.1:${port}/callback`
+      const authorizeUrl = `${base}/dev/auth/authorize?redirect_uri=${encodeURIComponent(redirectUri)}&state=${state}`
+      console.log('\x1b[36m→\x1b[0m Opening your browser to sign in…')
+      console.log(`  \x1b[2m${authorizeUrl}\x1b[0m`)
+      const opened = await openBrowser(authorizeUrl)
+      if (!opened) console.log('\x1b[33m⚠\x1b[0m Could not open a browser automatically — open the URL above.')
+      console.log('\x1b[2mWaiting for sign-in to complete (120s)…\x1b[0m')
+    })
+    timer = setTimeout(() => { server.close(); resolve({ error: 'timed out waiting for sign-in (120s).' }) }, 120000)
+  })
+
+  if (result.error) throw new Error(result.error)
+  let account = null
+  try { account = await fetchMe({ apiBase, token: result.token }) } catch { /* identity optional; token is valid */ }
+  const record = { token: result.token }
+  if (account?.uuid) record.uuid = account.uuid
+  if (account?.username) record.username = account.username
+  if (account?.handle) record.handle = account.handle
+  await writeRegistryAuth(record)
+  return record
+}
+
+/**
+ * `uniweb login` against the new backend — a multi-method picker:
+ *   browser/social (default, once available) · username+password · paste a token.
+ * Force a method with --browser / --password / --token-paste (skips the menu).
+ * No TTY → no menu; falls back to the non-browser path (env UNIWEB_USERNAME/
+ * PASSWORD; UNIWEB_TOKEN is handled earlier by ensureRegistryAuth).
+ *
+ * @param {Object} o
+ * @param {string} o.apiBase - new-backend origin
+ * @param {string[]} [o.args] - argv slice (force flags + --non-interactive)
+ * @returns {Promise<Object|undefined>} the stored session record
+ */
+export async function runRegistryLogin({ apiBase, args = [] } = {}) {
+  const existing = await readRegistryAuth()
+  if (existing?.token && !isExpired(existing)) {
+    const who = existing.username || existing.handle || (existing.uuid ? `account ${existing.uuid}` : '')
+    console.log(`Already logged in${who ? ` as \x1b[1m${who}\x1b[0m` : ''}${apiBase ? ` (${apiBase})` : ''}.`)
+    console.log('\x1b[2mContinuing will replace the existing session.\x1b[0m\n')
+  }
+
+  const { isNonInteractive } = await import('./interactive.js')
+  const nonInteractive = isNonInteractive(args)
+
+  let method = args.includes('--browser') ? 'browser'
+    : args.includes('--password') ? 'password'
+    : args.includes('--token-paste') ? 'token-paste'
+    : null
+
+  if (!method) {
+    if (nonInteractive) {
+      if (process.env.UNIWEB_USERNAME && process.env.UNIWEB_PASSWORD) {
+        method = 'password'
+      } else {
+        console.error('\x1b[31m✗\x1b[0m Cannot log in non-interactively without a method.')
+        console.error('  Set UNIWEB_USERNAME + UNIWEB_PASSWORD, set UNIWEB_TOKEN, or run `uniweb login` in a terminal.')
+        console.error('  Or force one: --password / --token-paste.')
+        process.exit(1)
+      }
+    } else {
+      const prompts = (await import('prompts')).default
+      const choices = []
+      if (BROWSER_AVAILABLE) choices.push({ title: 'Browser / social (Google, etc.)', value: 'browser' })
+      choices.push({ title: 'Username and password', value: 'password' })
+      choices.push({ title: 'Paste a token', value: 'token-paste' })
+      const { picked } = await prompts({
+        type: 'select', name: 'picked', message: 'How do you want to log in?', choices,
+      }, { onCancel: () => { console.log('\nLogin cancelled.'); process.exit(0) } })
+      if (!picked) process.exit(0)
+      method = picked
+    }
+  }
+
+  let record
+  try {
+    if (method === 'browser') record = await loginViaBrowser({ apiBase })
+    else if (method === 'token-paste') record = await loginViaTokenPaste({ apiBase, nonInteractive })
+    else record = await loginViaPassword({ apiBase, nonInteractive })
+  } catch (err) {
+    console.error(`\x1b[31m✗\x1b[0m ${err.message}`)
+    process.exit(1)
+  }
+
+  if (record?.token) {
+    console.log(`\x1b[32m✓\x1b[0m Logged in${record.username ? ` as \x1b[1m${record.username}\x1b[0m` : ''}${apiBase ? ` (${apiBase})` : ''}`)
+  }
+  return record
+}

package/src/utils/registry-orgs.js

@@ -0,0 +1,179 @@
+/**
+ * New-backend org operations for the publish-scope bootstrap — used by
+ * `uniweb register`'s scope resolution and the `uniweb org` command.
+ *
+ * One resource (Bearer auth, new backend); the verb selects the operation:
+ *   GET  /dev/orgs            → [{ handle, is_primary }] (your orgs, primary first)
+ *   POST /dev/orgs { handle }  → { handle, uuid, is_primary }  (creator becomes a
+ *                                member, primary iff their first)
+ *
+ * Handle grammar + reserved scopes are validated client-side for a clean prompt;
+ * the server is the backstop (409 taken-or-reserved, 422 bad grammar).
+ */
+
+const ORGS_PATH = '/dev/orgs'
+
+// Reserved registry scopes a dev cannot own — the system + standard namespaces
+// (uwx-format scope model). Grammatically valid, so the server returns 409
+// "taken" for these; we block them earlier for a clearer message.
+const RESERVED_HANDLES = new Set(['uniweb', 'std'])
+
+// Handle grammar (backend): lowercase alphanumerics + internal hyphens, 3–39 chars,
+// no leading/trailing hyphen. The server is authoritative on reserved names (409).
+const HANDLE_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/
+const HANDLE_MIN = 3
+const HANDLE_MAX = 39
+
+/** Strip a leading `@` and any `/suffix`, returning the bare handle segment. */
+export function bareHandle(scope) {
+  return String(scope || '').replace(/^@/, '').replace(/\/.*$/, '')
+}
+
+/**
+ * Validate a handle client-side. Returns an error string, or null when valid.
+ * Accepts an optional leading `@` (stripped before checking).
+ */
+export function validateHandle(handle) {
+  const h = bareHandle(handle)
+  if (!h) return 'A handle is required.'
+  if (h.length < HANDLE_MIN || h.length > HANDLE_MAX) return `Handle must be ${HANDLE_MIN}–${HANDLE_MAX} characters.`
+  if (!HANDLE_RE.test(h)) return 'Use lowercase letters, digits, and internal hyphens only (e.g. acme-co).'
+  if (RESERVED_HANDLES.has(h)) return `@${h} is reserved.`
+  return null
+}
+
+/**
+ * List the authenticated account's org memberships (primary first).
+ * @returns {Promise<Array<{handle: string, is_primary: boolean}>>}
+ */
+export async function listOrgs({ apiBase, token }) {
+  const res = await fetch(`${apiBase.replace(/\/$/, '')}${ORGS_PATH}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  })
+  if (!res.ok) throw new Error(`Could not list your orgs: HTTP ${res.status} ${res.statusText}`)
+  const data = await res.json().catch(() => null)
+  return Array.isArray(data) ? data : []
+}
+
+/**
+ * Create an org. The creating account becomes a member (primary iff it's their
+ * first), so it's immediately publishable.
+ * @returns {Promise<{handle: string, uuid?: string, is_primary?: boolean}>}
+ */
+export async function createOrg({ apiBase, token, handle }) {
+  const h = bareHandle(handle)
+  const res = await fetch(`${apiBase.replace(/\/$/, '')}${ORGS_PATH}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+    body: JSON.stringify({ handle: h }),
+  })
+  if (res.status === 409) {
+    const e = new Error(`@${h} is already taken (or reserved). Pick another.`)
+    e.status = 409
+    throw e
+  }
+  if (res.status === 422) {
+    const e = new Error(`@${h} is not a valid handle.`)
+    e.status = 422
+    throw e
+  }
+  if (!res.ok) {
+    let detail = ''
+    try { detail = (await res.text()).slice(0, 200) } catch { /* ignore */ }
+    const e = new Error(`Could not create @${h}: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`)
+    e.status = res.status
+    throw e
+  }
+  return res.json()
+}
+
+/**
+ * Derive the publish scope from login membership when none was supplied:
+ *   1 org  → use it (confirm once)
+ *   0 orgs → offer to create one (proposes the account handle when set, else
+ *            prompts — never username-derived; cold-start per handle-origin (ii))
+ *   N orgs → pick
+ * Returns the chosen bare handle (no `@`), or null if cancelled. Persists
+ * nothing — the caller records it. Bails in non-interactive mode.
+ *
+ * @param {Object} p
+ * @param {string} p.apiBase
+ * @param {string} p.token
+ * @param {string|null} [p.accountHandle] - the account's handle (may be null)
+ * @param {string[]} [p.args] - argv slice; checked for --non-interactive
+ * @returns {Promise<string|null>}
+ */
+export async function deriveScope({ apiBase, token, accountHandle = null, args = [] }) {
+  const orgs = await listOrgs({ apiBase, token })
+  const { isNonInteractive } = await import('./interactive.js')
+  const nonInteractive = isNonInteractive(args)
+
+  if (orgs.length === 1) {
+    const h = orgs[0].handle
+    if (nonInteractive) {
+      console.log(`Publishing under your org \x1b[1m@${h}\x1b[0m.`)
+      return h
+    }
+    const prompts = (await import('prompts')).default
+    const { ok } = await prompts({
+      type: 'confirm', name: 'ok', message: `Publish under your org @${h}?`, initial: true,
+    }, { onCancel: () => { console.log('\nCancelled.'); process.exit(0) } })
+    if (!ok) {
+      console.log('Pass --scope @org, or create another with `uniweb org create <handle>`.')
+      return null
+    }
+    return h
+  }
+
+  if (orgs.length > 1) {
+    if (nonInteractive) {
+      const primary = orgs.find((u) => u.is_primary) || orgs[0]
+      console.log(`Multiple orgs; using primary \x1b[1m@${primary.handle}\x1b[0m (non-interactive).`)
+      return primary.handle
+    }
+    const prompts = (await import('prompts')).default
+    const { choice } = await prompts({
+      type: 'select',
+      name: 'choice',
+      message: 'Publish under which org?',
+      choices: orgs.map((u) => ({ title: `@${u.handle}${u.is_primary ? ' (primary)' : ''}`, value: u.handle })),
+    }, { onCancel: () => { console.log('\nCancelled.'); process.exit(0) } })
+    return choice || null
+  }
+
+  // 0 orgs → offer to create.
+  if (nonInteractive) {
+    console.error('\x1b[31m✗\x1b[0m You have no org to publish under. Create one with `uniweb org create <handle>`, or pass --scope @org.')
+    process.exit(1)
+  }
+  return offerCreateOrg({ apiBase, token, accountHandle })
+}
+
+/**
+ * Cold-start: prompt for a handle (pre-filled with the account handle when it's
+ * set + valid — never the username), create the org, return its handle.
+ * @returns {Promise<string|null>}
+ */
+export async function offerCreateOrg({ apiBase, token, accountHandle = null }) {
+  const prompts = (await import('prompts')).default
+  const suggested = accountHandle && !validateHandle(accountHandle) ? bareHandle(accountHandle) : ''
+
+  console.log("You don't have an org yet — let's create one (it becomes your publish scope).")
+  const { handle } = await prompts({
+    type: 'text',
+    name: 'handle',
+    message: 'Org handle (e.g. acme):',
+    initial: suggested,
+    validate: (v) => validateHandle(v) || true,
+  }, { onCancel: () => { console.log('\nCancelled.'); process.exit(0) } })
+  if (!handle) return null
+
+  try {
+    const org = await createOrg({ apiBase, token, handle })
+    console.log(`\x1b[32m✓\x1b[0m Created \x1b[1m@${org.handle}\x1b[0m — you're a member${org.is_primary ? ' (primary)' : ''}.`)
+    return org.handle
+  } catch (err) {
+    console.error(`\x1b[31m✗\x1b[0m ${err.message}`)
+    return null
+  }
+}