uniweb 1.0.0 → 1.0.2

package/src/backend/workspace.js

@@ -0,0 +1,234 @@
+/**
+ * THE WORKSPACE A COMMAND WORKS IN — one at a time, chosen with the login.
+ *
+ * ⭐ **[Diego, 2026-09-23]** — *"when a user has workspace in the backend, I expected them
+ * to explicitly login into one"*, and a site the backend keeps in ANOTHER workspace is
+ * refused rather than worked on anyway: *"that's the intent of the workspace concept."*
+ * The app keeps one workspace per tab; the CLI keeps one per login, and every site
+ * request names it (`x-uniweb-workspace`, `client.js`). A site outside it answers `409
+ * wrong_workspace`, and the command stops, saying how to switch — nothing is adopted.
+ *
+ * Where a command's workspace comes from — the first answer wins:
+ *
+ *   1. `--org @acme` / `--personal`     this command only
+ *   2. `UNIWEB_WORKSPACE=@acme|personal` a process logged in with `UNIWEB_TOKEN`, which has
+ *                                        no `uniweb login` to choose one (a template
+ *                                        installer, an agent driving several backends)
+ *   3. the one chosen at `uniweb login`  the session's
+ *   4. none chosen                       your personal workspace when you belong to no
+ *                                        organization; otherwise refused, naming 1–3
+ *
+ * New sites are created in it: a create names the workspace, and the workspace is the
+ * site's owner.
+ *
+ * ⛔ **The personal workspace is named by naming NONE.** `@<your handle>` is your personal
+ * SCOPE — a registry namespace for foundations and data schemas — not a workspace.
+ */
+
+import { readOrgFlag } from '../utils/args.js'
+import { loginCommand } from '../utils/config.js'
+import { fetchOrgs, bareHandle, validateHandle } from '../utils/registry-orgs.js'
+import { readRegistryAuth } from '../utils/registry-auth.js'
+import { workspaceHandle, describeWorkspace } from './client.js'
+
+export { describeWorkspace }
+
+/** The personal workspace, as a login stores the choice (a handle is stored with its `@`). */
+export const PERSONAL = 'personal'
+
+/** Names a process's workspace when it is logged in with `UNIWEB_TOKEN`. */
+export const WORKSPACE_ENV = 'UNIWEB_WORKSPACE'
+
+/**
+ * A workspace choice as it may be written — `@acme`, `acme`, `personal` — or null when
+ * the value names none.
+ *
+ * @param {unknown} value
+ * @returns {string|null} `@acme`, `PERSONAL`, or null
+ */
+export function parseWorkspaceChoice(value) {
+  if (typeof value !== 'string' || !value.trim()) return null
+  const v = value.trim()
+  return v === PERSONAL ? PERSONAL : workspaceHandle(v)
+}
+
+/** A choice in the header's form: `@acme`, or null for the personal workspace. */
+export function headerOf(choice) {
+  return choice === PERSONAL ? null : choice
+}
+
+/** What a source is called in a sentence — "(… )" after the workspace. */
+export const SOURCE_LABEL = {
+  flag: 'named on this command',
+  env: WORKSPACE_ENV,
+  login: 'your login',
+  personal: 'you belong to no organization',
+  offline: 'not resolved in a preview'
+}
+
+/** How to choose, for a command on `origin` — its login names the backend when it must (`loginCommand`). */
+const choose = (origin) =>
+  [
+    'Choose the workspace you work in:',
+    `    ${loginCommand(origin)} --org @acme   (or --personal) — for every command after`,
+    '    --org @acme / --personal      — for this command only',
+    `    ${WORKSPACE_ENV}=@acme        — for a process logged in with UNIWEB_TOKEN`
+  ].join('\n')
+
+/**
+ * The workspace this command works in.
+ *
+ * @param {object} p
+ * @param {import('./client.js').BackendClient} p.client - its origin and token
+ * @param {string[]} [p.args]
+ * @param {boolean} [p.offline=false] - a preview (`--dry-run`, `-o`): never authenticates,
+ *   so step 4 answers "not resolved" instead of asking the backend
+ * @returns {Promise<{ workspace: string|null, source: string } | { refused: true, reason: string }>}
+ *   `workspace` in the header's form — `@acme`, or null for the personal workspace
+ */
+export async function resolveWorkspace({ client, args = [], offline = false }) {
+  const flag = readOrgFlag(args)
+  if (flag) return { workspace: workspaceHandle(flag), source: 'flag' }
+  if (args.includes('--personal')) return { workspace: null, source: 'flag' }
+
+  const raw = process.env[WORKSPACE_ENV]
+  if (raw !== undefined && raw !== '') {
+    const env = parseWorkspaceChoice(raw)
+    if (!env) {
+      return {
+        refused: true,
+        reason: `${WORKSPACE_ENV}=${JSON.stringify(raw)} names no workspace — give @org, or ${PERSONAL}.`
+      }
+    }
+    return { workspace: headerOf(env), source: 'env' }
+  }
+
+  // ⛔ A process logged in with UNIWEB_TOKEN is not the session's login: the token may be
+  // another account's, so the session's workspace is not its to use.
+  const useSession = !process.env.UNIWEB_TOKEN
+  const fromSession = async () =>
+    useSession ? parseWorkspaceChoice((await readRegistryAuth(client.origin))?.workspace) : null
+
+  const chosen = await fromSession()
+  if (chosen) return { workspace: headerOf(chosen), source: 'login' }
+  if (offline) return { workspace: null, source: 'offline' }
+
+  // Authenticate — a login this triggers chooses a workspace, so ask the session again.
+  await client.token()
+  const now = await fromSession()
+  if (now) return { workspace: headerOf(now), source: 'login' }
+
+  const { orgs } = await client.fetchOrgs()
+  if (!orgs.length) return { workspace: null, source: 'personal' }
+  return {
+    refused: true,
+    reason: `You belong to organizations, so no workspace is assumed.\n  ${choose(client.origin)}`
+  }
+}
+
+/**
+ * The scope a bare name registers under by default — the workspace the command works in
+ * *[Diego, 2026-10-06]*: an organization's handle, or your own handle for your personal
+ * workspace.
+ *
+ * ⭐ A default, asked once: a name that carries a scope keeps it, and `--scope` names
+ * another. The workspace still never decides anything else about a foundation — it
+ * decides which SITE a command works on; here it only answers the question a bare name
+ * asks the first time it registers.
+ *
+ * Null when the workspace names no scope, and the caller derives one as before
+ * (`deriveScope`): none is chosen (you belong to organizations and none is named), the
+ * command is a preview, the workspace is a unit without a handle, or the account has no
+ * handle (a service account).
+ *
+ * @param {{ workspace?: string|null, source?: string, refused?: boolean }} ws -
+ *   `resolveWorkspace`'s answer
+ * @param {string|null} accountHandle - the account's own handle (`GET /dev/orgs`), read
+ *   only for the personal workspace
+ * @returns {string|null} `@handle`
+ */
+export function scopeOfWorkspace(ws, accountHandle) {
+  if (!ws || ws.refused || ws.source === 'offline') return null
+  if (typeof ws.workspace === 'string') return ws.workspace.startsWith('@') ? ws.workspace : null
+  const h = bareHandle(accountHandle || '')
+  return h && !validateHandle(h) ? `@${h}` : null
+}
+
+/**
+ * The workspace a login works in — asked once, at `uniweb login`, and stored with the
+ * session.
+ *
+ *   `--org @acme`            must be an organization you belong to
+ *   `--personal`             your personal workspace
+ *   neither, no organization your personal workspace — said, not asked
+ *   neither, organizations   a pick at a terminal; refused without one
+ *
+ * @param {object} p
+ * @param {string} p.apiBase
+ * @param {string} p.token
+ * @param {string[]} [p.args]
+ * @returns {Promise<{ choice: string, note?: string } | { refused: true, reason: string }>}
+ *   `choice` is `@acme` or `PERSONAL`
+ */
+export async function chooseWorkspace({ apiBase, token, args = [] }) {
+  const flag = readOrgFlag(args)
+  if (!flag && args.includes('--personal')) return { choice: PERSONAL }
+
+  const { orgs } = await fetchOrgs({ apiBase, token })
+  const mine = orgs.map((o) => `@${o.handle}`)
+  if (flag) {
+    const h = workspaceHandle(flag)
+    if (!mine.includes(h)) {
+      return {
+        refused: true,
+        reason:
+          `You are not a member of ${h} on ${apiBase}. ` +
+          (mine.length
+            ? `Your workspaces: ${[...mine, `--personal`].join(', ')}.`
+            : 'You belong to no organization — use --personal.')
+      }
+    }
+    return { choice: h }
+  }
+  if (!orgs.length) {
+    return {
+      choice: PERSONAL,
+      note: 'You belong to no organization, so you work in your personal workspace.'
+    }
+  }
+
+  const { isNonInteractive, getCliPrefix } = await import('../utils/interactive.js')
+  // ⭐ How to choose, said whole: the session is stored already (`registry-auth.js`, the
+  // login methods), so the login that finishes this signs nobody in again.
+  const others = [...mine.slice(1).map((h) => `--org ${h}`), '--personal']
+  const howToChoose =
+    `Choose one: ${loginCommand(apiBase, getCliPrefix())} --org ${mine[0]} (or ${others.join(', ')}) — ` +
+    'it will not ask you to sign in again.'
+  if (isNonInteractive(args)) {
+    return {
+      refused: true,
+      reason: `You belong to organizations, so no workspace is assumed. ${howToChoose}`
+    }
+  }
+  const prompts = (await import('prompts')).default
+  const { choice } = await prompts(
+    {
+      type: 'select',
+      name: 'choice',
+      message: 'Which workspace do you work in?',
+      choices: [
+        { title: 'Personal — your own sites', value: PERSONAL },
+        ...orgs.map((o) => ({
+          title: `@${o.handle}${o.is_primary ? ' (primary)' : ''}`,
+          value: `@${o.handle}`
+        }))
+      ],
+      initial: 0
+    },
+    // ⛔ A cancelled pick is NOT a cancelled login: the session is stored already, so the
+    // login says so and how to finish it (`finishLogin`), and exits 2. Until 2026-10-06 this
+    // printed "Cancelled." and exited 0 — with the new session in place of the old one.
+    { onCancel: () => false }
+  )
+  return choice ? { choice } : { refused: true, reason: `No workspace chosen. ${howToChoose}` }
+}