@datumos/datum-cli 0.0.0 → 0.589.0

package/cli/spaceRepoTemplate.js

@@ -0,0 +1,463 @@
+/**
+ * The files `datum space-manifest init <dir>` writes (#1809): a repository
+ * that keeps ONE space's configuration as code — the manifest files under
+ * `space/`, a CI that plans on a pull request and applies on `main`, a
+ * daily sync that brings panel edits back as a pull request, and the rules
+ * for whoever (or whatever agent) edits it. No Terraform, no state: the
+ * server plans every change against the live space
+ * (docs/space-admin/space-repository.md).
+ */
+/** Where the manifest files live inside the repository. */
+export const SPACE_REPO_MANIFEST_DIR = "space";
+/** The repository secret the workflows read — a key bound to the space. */
+export const SPACE_REPO_KEY_SECRET = "DATUM_SPACE_API_KEY";
+/** The repository variable with the organisation host. */
+export const SPACE_REPO_BASE_URL_VAR = "DATUM_BASE_URL";
+/** The branch the sync workflow opens its pull request from. */
+export const SPACE_REPO_SYNC_BRANCH = "datum/sync-from-space";
+/** The public package the workflows install (docs/cli.md "Running it"). */
+export const DATUM_CLI_NPM_PACKAGE = "@datumos/datum-cli";
+/** The recommended repository name: the team's namespace first, like the
+ * namespace's other repositories (repositories are created in Cloud Market,
+ * in a namespace's "GitHub repositories" purchase, never directly in GitHub). */
+export function recommendedSpaceRepoName(space, namespace = "<namespace>") {
+    return `${namespace}-datum-space-${space}`;
+}
+const DIR = SPACE_REPO_MANIFEST_DIR;
+function installCli() {
+    return `      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Install the datum CLI
+        run: |
+          npm install -g ${DATUM_CLI_NPM_PACKAGE}`;
+}
+function planApplyWorkflow(space) {
+    return `# The space's configuration as code: plan on a pull request, apply on main.
+# Written by \`datum space-manifest init\` — docs/space-admin/space-repository.md.
+#
+# Repository settings it needs:
+#   secret   ${SPACE_REPO_KEY_SECRET}  a key bound to the space "${space}", role admin
+#                                (panel: Settings → API keys)
+#   variable ${SPACE_REPO_BASE_URL_VAR}       the organisation host, e.g. https://datum.example.com
+name: Datum space
+
+on:
+  # The plan needs the space key, so it runs as pull_request_TARGET: the
+  # workflow comes from the base branch (a pull request cannot edit what
+  # runs with the key) and the pull request is checked out only as DATA —
+  # the manifest files — never executed. Every pull request gets a plan
+  # (no paths filter), so a required "plan" check never blocks one that
+  # does not touch ${DIR}/.
+  pull_request_target:
+  push:
+    branches: [main]
+    paths: ["${DIR}/**", ".github/workflows/datum-space.yml"]
+  # Run on main to re-apply the repository — e.g. after closing a sync pull
+  # request to revert an edit made in the panel. Tick "prune" to delete the
+  # entries whose files a merged pull request removed.
+  workflow_dispatch:
+    inputs:
+      prune:
+        description: Delete space entries the files no longer name (within the kinds space/ declares)
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+env:
+  DATUM_BASE_URL: \${{ vars.${SPACE_REPO_BASE_URL_VAR} }}
+  DATUM_SPACE: ${space}
+
+jobs:
+  plan:
+    if: github.event_name == 'pull_request_target'
+    runs-on: [self-hosted, ubuntu-latest, ARM64]
+    # Per pull request: a new push supersedes that PR's running plan only.
+    concurrency:
+      group: datum-space-plan-\${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      # The pull request's files land in pr/ as data: no script, hook, .npmrc
+      # or workflow of theirs runs — the steps below run from the workspace
+      # root with the base branch's definitions.
+      - uses: actions/checkout@v6
+        with:
+          ref: \${{ github.event.pull_request.head.sha }}
+          path: pr
+          persist-credentials: false
+${installCli()}
+      - name: Plan (dry run against the live space)
+        run: |
+          if [ ! -d pr/${DIR} ]; then echo "No ${DIR}/ yet — run the Datum space sync workflow to import the space."; exit 0; fi
+          # A refused plan replaces the comment too — never leave an older,
+          # successful plan standing on a pull request that no longer plans.
+          if ! datum space-manifest push pr/${DIR} --dry-run --markdown plan.md 2> plan.err; then
+            cat plan.err
+            { printf '## Datum space plan\\n\\n**The plan was refused** — nothing can be applied until this is fixed:\\n\\n\`\`\`\\n'; cat plan.err; printf '\`\`\`\\n'; } > plan.md
+            exit 1
+          fi
+        env:
+          DATUM_API_KEY: \${{ secrets.${SPACE_REPO_KEY_SECRET} }}
+      - name: Comment the plan on the pull request
+        if: always() && hashFiles('plan.md') != ''
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const marker = '<!-- datum-space-plan -->';
+            const body = \`\${marker}\\n\${fs.readFileSync('plan.md', 'utf8')}\`;
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.pull_request.number;
+            const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number });
+            const mine = comments.find((c) => c.body?.startsWith(marker));
+            if (mine) await github.rest.issues.updateComment({ owner, repo, comment_id: mine.id, body });
+            else await github.rest.issues.createComment({ owner, repo, issue_number, body });
+
+  apply:
+    # push / manual run on main ONLY — a pull_request_target run carries
+    # ref = main too, and must never re-apply main because a PR was opened.
+    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
+    runs-on: [self-hosted, ubuntu-latest, ARM64]
+    # Applies queue one after another; a newer pending apply replaces an
+    # older pending one, which is fine — both apply main as it is now.
+    concurrency:
+      group: datum-space-apply
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v6
+${installCli()}
+      - name: Apply
+        run: |
+          if [ ! -d ${DIR} ]; then echo "No ${DIR}/ yet — nothing to apply."; exit 0; fi
+          datum space-manifest push ${DIR} $PRUNE --markdown apply.md
+          cat apply.md >> "$GITHUB_STEP_SUMMARY"
+        env:
+          DATUM_API_KEY: \${{ secrets.${SPACE_REPO_KEY_SECRET} }}
+          PRUNE: \${{ inputs.prune && '--prune' || '' }}
+      # After a clean apply the space equals the files, so a second dry run
+      # must plan zero writes. A write here = a value the server normalises
+      # (write it the way the plan shows) or a panel edit racing the apply.
+      - name: Verify convergence
+        run: |
+          if [ ! -d ${DIR} ]; then exit 0; fi
+          datum space-manifest push ${DIR} $PRUNE --dry-run --expect-empty
+        env:
+          DATUM_API_KEY: \${{ secrets.${SPACE_REPO_KEY_SECRET} }}
+          PRUNE: \${{ inputs.prune && '--prune' || '' }}
+`;
+}
+function syncWorkflow(space) {
+    return `# Brings the space's live configuration into the repository as a pull request.
+# Written by \`datum space-manifest init\` — docs/space-admin/space-repository.md.
+#
+# - First run = the IMPORT (Actions → Datum space sync → Run workflow): a new
+#   repository has no ${DIR}/ yet; merge the pull request it opens.
+# - Every weekday morning after that = DRIFT: an edit made in the panel comes
+#   back as a pull request. Merge it to keep the edit; close it and the next
+#   apply restores what the repository says.
+#
+# The pull request is opened with the workflow's GITHUB_TOKEN, for which
+# GitHub starts no workflows: its plan does not run. A sync pull request
+# mirrors the space, so its plan is empty by construction.
+name: Datum space sync
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 5 * * 1-5"
+
+# Its own group: a queued sync must never cancel a pending apply (GitHub
+# keeps one pending run per group). Instead the sync stays away from an
+# apply in flight — it would read a half-applied space — see the steps.
+concurrency:
+  group: datum-space-sync
+  cancel-in-progress: false
+
+permissions:
+  actions: read
+  contents: write
+  pull-requests: write
+
+env:
+  DATUM_BASE_URL: \${{ vars.${SPACE_REPO_BASE_URL_VAR} }}
+  DATUM_SPACE: ${space}
+
+jobs:
+  sync:
+    runs-on: [self-hosted, ubuntu-latest, ARM64]
+    steps:
+      - uses: actions/checkout@v6
+${installCli()}
+      - name: Wait until no apply is running
+        id: idle
+        env:
+          GH_TOKEN: \${{ github.token }}
+        run: |
+          applying() {
+            gh run list --workflow datum-space.yml --limit 20 --json status,event \\
+              --jq '[.[] | select(.event != "pull_request_target" and .status != "completed")] | length'
+          }
+          for _ in $(seq 1 30); do [ "$(applying)" = "0" ] && break; sleep 20; done
+          if [ "$(applying)" != "0" ]; then
+            echo "An apply is still running — skipping this sync; the next one sees the result."
+            echo "skip=1" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Pull the live configuration
+        if: steps.idle.outputs.skip != '1'
+        run: datum space-manifest pull ${DIR}
+        env:
+          DATUM_API_KEY: \${{ secrets.${SPACE_REPO_KEY_SECRET} }}
+      - name: Open or update the sync pull request
+        if: steps.idle.outputs.skip != '1'
+        env:
+          GH_TOKEN: \${{ github.token }}
+        run: |
+          # An apply that started while we pulled may have left a half-applied
+          # state in the files — drop this round rather than propose it.
+          if [ "$(gh run list --workflow datum-space.yml --limit 20 --json status,event --jq '[.[] | select(.event != "pull_request_target" and .status != "completed")] | length')" != "0" ]; then
+            echo "An apply started during the pull — skipping; the next sync sees the result."
+            exit 0
+          fi
+          git add -A ${DIR}
+          if git diff --cached --quiet; then
+            echo "The repository already matches the space."
+            exit 0
+          fi
+          # ${DIR}/ already on main = drift; absent = the first import.
+          if [ -n "$(git ls-tree -d --name-only HEAD ${DIR})" ]; then
+            title="Sync z przestrzeni: zmiany spoza repozytorium"
+            body="Konfiguracja przestrzeni ${space} różni się od repozytorium — ktoś zmienił ją w panelu albo innym narzędziem. Zmerguj, żeby zachować zmianę. Żeby ją cofnąć: zamknij i uruchom workflow Datum space na main (Run workflow) — przywróci stan z repozytorium."
+          else
+            title="Import konfiguracji przestrzeni ${space}"
+            body="Pierwszy import: stan przestrzeni ${space} jako pliki w ${DIR}/. Po merge apply nie powinien nic zmienić (plan = same noop)."
+          fi
+          git config user.name "datum-space-sync"
+          git config user.email "github-actions@users.noreply.github.com"
+          git checkout -B ${SPACE_REPO_SYNC_BRANCH}
+          git commit -m "$title"
+          git push --force origin ${SPACE_REPO_SYNC_BRANCH}
+          if [ -z "$(gh pr list --head ${SPACE_REPO_SYNC_BRANCH} --state open --json number --jq '.[].number')" ]; then
+            gh pr create --head ${SPACE_REPO_SYNC_BRANCH} --title "$title" --body "$body" || {
+              echo "::error::Could not open the pull request. Turn on Settings → Actions → General → \\"Allow GitHub Actions to create and approve pull requests\\" (off by default), then re-run. The branch ${SPACE_REPO_SYNC_BRANCH} is pushed — a person can open the pull request from it meanwhile."
+              exit 1
+            }
+          fi
+`;
+}
+function agentsMd(space) {
+    return `# Working in the Datum space repository \`${space}\`
+
+This repository holds the configuration of the Datum space \`${space}\` as
+files. \`main\` is what the space runs: a merge applies it through the space
+manifest. There is no Terraform and no state file — the server plans every
+change against the live space.
+
+## Layout (\`${DIR}/\`)
+
+| Path | What it is |
+| --- | --- |
+| \`${DIR}/space.json\` | \`apiVersion\` + scalar kinds (\`autonomyOptIn\`, \`skillsRepoUrl\`) |
+| \`${DIR}/<kind>.json\` | a map kind: \`settings\`, \`github\`, \`jira\`, \`teams\`, \`victorops\`, \`grafanaAlerts\`, \`credentialBindings\` |
+| \`${DIR}/<kind>/<entry>.json\` | one entry of a list kind: \`agents\`, \`routines\`, \`flows\`, \`queues\`, \`caseBoards\`, \`knowledgeBases\`, \`credentials\`, … |
+| \`${DIR}/<kind>/<entry>.prompt.md\` | the entry's prompt (agents, routines) |
+| \`${DIR}/<kind>/<entry>.<field>.json\` | a large JSON field: routine \`inputSchema\`/\`outputSchema\`, flow \`definition\` |
+
+An extracted field is referenced from its entry as \`{ "$file": "<name>" }\`.
+Every kind's fields, with descriptions: \`datum space-manifest schema <kind>
+--space ${space}\` (no kind = the whole schema). Every \`datum\` command below
+names the space with \`--space ${space}\`: a sign-in addresses the
+organisation's host otherwise, where a space member has no authority.
+
+## Creating something new (an agent, a routine, a flow, a queue…)
+
+1. **Take the shape from Datum, nowhere else.** \`datum space-manifest schema
+   <kind> --space ${space}\` lists the kind's fields and what each means. For a
+   flow, look in the flow catalog first (\`datum flow-catalog entries list
+   --space ${space}\`, then \`datum flow-catalog entries get <id> --space ${space}\`)
+   — flows other spaces published and the organisation certified; one that
+   fits is installed through \`flowInstalls\`, not copied — and read the step
+   types in \`datum flows create --help\`. An entry already in \`${DIR}/\` is a
+   good second example.
+2. **Do not read other spaces' repositories, other spaces' configuration or
+   the \`datum-core\` source** to learn a shape. They are other teams' local
+   decisions, with queues, credentials and people that do not exist here,
+   and source code is not the contract — the schema, the catalog and
+   \`--help\` are.
+3. **Ask the space what it is for.** \`datum a2a send --space ${space} "…"\` hands
+   a question to the space's own agent: which routine already does this,
+   which queue triages it, who approves.
+4. **People by nick.** A routine's \`owner\`, an approver, a queue member: a
+   person of this space — \`datum space-members list --space ${space}\` (the
+   \`userId\` of a row is the nick; \`derived\` lists the people a bound Entra
+   group admits). Never an e-mail or an id.
+5. **Check before the pull request.** \`datum space-manifest validate ${DIR}
+   --space ${space}\` must pass (any member can run it: for a space admin it is the dry
+   run's full check, below admin the shape only). It calls the server, so it
+   needs a sign-in (\`datum login\`) or a key in \`DATUM_API_KEY\` — like \`schema\`;
+   offline or signed out both answer "not signed in". A space
+   admin also sees the plan against the live space: \`datum space-manifest
+   push ${DIR} --dry-run --space ${space}\`.
+
+A minimal new routine is two files — the entry, named after its \`name\`
+(lower-case, dashes; \`pull\` keeps that name), and its prompt next to it:
+
+\`${DIR}/routines/raport-dnia.json\`
+
+\`\`\`json
+{
+  "name": "Raport dnia",
+  "prompt": { "$file": "raport-dnia.prompt.md" },
+  "owner": "<nick from datum space-members list>",
+  "cron": "0 7 * * 1-5",
+  "timezone": "Europe/Warsaw"
+}
+\`\`\`
+
+\`${DIR}/routines/raport-dnia.prompt.md\` — the prompt itself, in Polish. No
+\`cron\` (or \`""\`) = the routine runs on demand only; every other field
+(\`inputSchema\`, \`triggers\`, \`runsAs\`, …) is in \`datum space-manifest
+schema routines --space ${space}\`.
+
+## Rules
+
+1. **Change files, never the space directly.** Edit under \`${DIR}/\`, open a
+   pull request, read the plan the CI comments, merge. An edit made in the
+   panel comes back as a "Sync z przestrzeni" pull request.
+2. **\`main\` applies.** Plan locally as much as you like (\`push --dry-run\`, a
+   space admin's sign-in is enough). Apply from a workstation (\`push\`
+   without \`--dry-run\`) only when the person asks for it AND the same change
+   is on its way to \`main\` — otherwise the next apply on \`main\` reverts it.
+3. **No secrets, ever.** A credential is declared by \`label\` + \`type\`; a
+   person fills its material in the panel. \`push\` refuses strings in common
+   key and token formats — a safety net, not a guarantee. Never print
+   \`DATUM_API_KEY\`.
+4. **The repository mirrors the whole space; deleting is explicit.** The
+   sync writes every entry the space has. Removing a file does NOT delete
+   the entry: the plan reports it as \`orphan\`. To delete: remove the file
+   in a pull request, merge, then run **Actions → Datum space → Run workflow**
+   on \`main\` with **prune** ticked (it deletes only within kinds \`${DIR}/\`
+   still declares). The panel refuses deleting some entries the repository
+   manages (a routine answers 409) — the repository is the way.
+5. **A new entry gets its defaults from the server.** The sync after the
+   merge brings the entry back with every field filled in (and a file name
+   derived from its key) — merge that pull request; it is not a panel edit.
+6. **Organisation-tier kinds do not live here** (\`features\`,
+   \`monthlyBudgetUsd\`, \`allocation\`, \`members\`, grants) — the org admin
+   decides them. A kind whose feature is off for the organisation is
+   refused by the plan: ask an org admin.
+7. **Natural keys, never ids**: agents by nick (\`id\`), routines and flows by
+   \`name\`, credentials by \`label\`; a flow step names its routine by name.
+8. **Domain content is Polish** — prompts, descriptions. Keys and file names
+   stay as \`pull\` wrote them.
+9. **Write values the way the server stores them.** When "Verify
+   convergence" fails after an apply, the server normalised a value: copy
+   the form the plan shows into the file.
+
+## Identity
+
+\`datum login\` signs a person in with their own role in the space — the same
+as in the panel (\`datum whoami --space ${space}\` shows it). Any member can read
+the schema and validate; a space admin can also pull and plan from a
+workstation. The CI plans and applies with \`${SPACE_REPO_KEY_SECRET}\`, a key
+bound to this space that lives only in the repository's secrets.
+
+The \`datum\` Claude Code plugin gives an agent the space's tools as the
+signed-in person; \`datum a2a send --space ${space} "…"\` hands a question to
+the space's own agent — ask it what a routine or a flow is for before
+changing it.`;
+}
+/** The markers around the part of AGENTS.md / CLAUDE.md Datum owns (#1824):
+ * a second \`datum space-manifest init\` replaces what is between them with the
+ * current text — the team's own notes outside them stay. */
+export const SPACE_REPO_MANAGED_BEGIN = "<!-- datum:managed:begin — written by `datum space-manifest init`; a re-run replaces this block. Add your own notes below the end marker. -->";
+export const SPACE_REPO_MANAGED_END = "<!-- datum:managed:end -->";
+function managedBlock(body) {
+    return `${SPACE_REPO_MANAGED_BEGIN}\n${body.trimEnd()}\n${SPACE_REPO_MANAGED_END}\n`;
+}
+/** The first line of an AGENTS.md written before the managed block existed
+ * (0.530.0) — such a file is Datum's whole, so a re-run replaces it. */
+const LEGACY_AGENTS_TITLE = "# Working in the Datum space repository";
+/**
+ * What a re-run of init writes into an existing AGENTS.md / CLAUDE.md:
+ * the block between the markers replaced; a pre-marker file Datum wrote
+ * whole (the legacy AGENTS.md, the one-line CLAUDE.md) replaced; any other
+ * file keeps its text and gets the block appended. `null` = already current.
+ */
+export function refreshManagedFile(existing, generated) {
+    const begin = existing.indexOf(SPACE_REPO_MANAGED_BEGIN);
+    const end = existing.indexOf(SPACE_REPO_MANAGED_END);
+    const block = generated.slice(0, generated.indexOf(SPACE_REPO_MANAGED_END) + SPACE_REPO_MANAGED_END.length);
+    let next;
+    if (begin !== -1 && end > begin) {
+        next = existing.slice(0, begin) + block + existing.slice(end + SPACE_REPO_MANAGED_END.length);
+    }
+    else if (existing.startsWith(LEGACY_AGENTS_TITLE) || existing.trim() === "@AGENTS.md") {
+        next = generated;
+    }
+    else {
+        next = `${existing.trimEnd()}\n\n${block}\n`;
+    }
+    return next === existing ? null : next;
+}
+/** Files of the repository Datum owns whole (the workflows, the line-ending
+ * rule): `init --refresh` overwrites them with the current version — e.g.
+ * to get the apply workflow's prune input into a repository set up before. */
+export const SPACE_REPO_DATUM_OWNED = new Set([
+    ".github/workflows/datum-space.yml",
+    ".github/workflows/datum-space-sync.yml",
+    ".gitattributes",
+]);
+/** Files with a managed block — every re-run of init refreshes the block. */
+export const SPACE_REPO_MANAGED_BLOCK_FILES = new Set(["AGENTS.md", "CLAUDE.md"]);
+function readme(space) {
+    return `# Datum space \`${space}\` — configuration as code
+
+The agents, routines, flows, connectors and boards of the Datum space
+\`${space}\`, kept as files in \`${DIR}/\` and applied on every merge to \`main\`.
+
+## Changing the space
+
+1. Edit files under \`${DIR}/\` (prompts are \`*.prompt.md\`) and open a pull request.
+2. The CI comments the plan: what will be created, updated, left alone.
+3. Merge — the CI applies it and checks that a second plan is empty.
+
+An edit made in the panel comes back as a "Sync z przestrzeni" pull request
+on the next weekday morning. Merge it to keep the edit. To revert it, close
+the pull request and run **Actions → Datum space → Run workflow** on main —
+that re-applies the repository (an apply otherwise runs only when a merge
+touches \`${DIR}/\`).
+
+## Setup (once)
+
+| Where | What |
+| --- | --- |
+| Settings → Actions → General | **Allow GitHub Actions to create and approve pull requests** (off by default — the sync needs it) |
+| Runners | the workflows run on \`[self-hosted, ubuntu-latest, ARM64]\` — the organisation's runner group must serve this repository |
+| Repository variable \`${SPACE_REPO_BASE_URL_VAR}\` | the organisation host, e.g. \`https://datum.example.com\` |
+| Repository secret \`${SPACE_REPO_KEY_SECRET}\` | a key bound to \`${space}\`, role **admin** — panel: Settings → API keys |
+| First import | Actions → **Datum space sync** → Run workflow, then merge its pull request |
+
+Rules for people and agents editing this repository: [AGENTS.md](AGENTS.md).
+`;
+}
+/** Every file of a fresh space repository, keyed by its path. */
+export function spaceRepoFiles(space) {
+    return {
+        ".github/workflows/datum-space.yml": planApplyWorkflow(space),
+        ".github/workflows/datum-space-sync.yml": syncWorkflow(space),
+        "AGENTS.md": `${managedBlock(agentsMd(space))}\n## Team notes\n\nYour team's own rules for this repository go here, below the managed block — \`datum space-manifest init\` keeps them.\n`,
+        "CLAUDE.md": managedBlock("@AGENTS.md"),
+        "README.md": readme(space),
+        ".gitignore": "plan.md\napply.md\nnode_modules/\n.DS_Store\n",
+        // Git for Windows checks text out with CRLF by default (core.autocrlf):
+        // a prompt file would then carry \r on every line and plan as changed.
+        // The manifest files stay LF on every machine, byte for byte as `pull`
+        // wrote them.
+        ".gitattributes": `${DIR}/** text eol=lf\n.github/workflows/** text eol=lf\n`,
+    };
+}
+//# sourceMappingURL=spaceRepoTemplate.js.map

package/cli/updateCommand.js

@@ -0,0 +1,184 @@
+/**
+ * `datum update` (#1512) — the foreground face of selfUpdate.ts.
+ *
+ *   datum update                 install the release the server runs, when newer
+ *   datum update --check         what runs here, what the server offers, the mode
+ *   datum update --to <version>  switch to an installed version (rollback)
+ *   datum update --to package    back to the npm-installed package
+ *   datum update --auto on|off   the person's opt-out (DATUM_AUTOUPDATE wins over it)
+ *   datum update --background    the detached check the launcher starts (silent)
+ */
+import { checkBundleSignature } from "./bundleSignature.js";
+import { AUTOUPDATE_MIN_ONLY, AUTOUPDATE_OFF, CLI_PACKAGE_NAME, CLI_PACKAGE_NAMES, ENV_LAUNCHER_VERSION, autoUpdateMode, checkForUpdate, clearCurrent, compareVersions, describeWhen, effectiveVersion, fetchLatest, installDeferredUntil, installedVersions, isPackagedInstall, oneLine, readCurrent, readState, switchTo, takeNotice, writeState, } from "./selfUpdate.js";
+const KNOWN_FLAGS = new Set(["check", "to", "auto", "background"]);
+function parse(args) {
+    const flags = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const t = args[i];
+        if (!t.startsWith("--"))
+            throw new Error(`unexpected argument \`${t}\` — see: datum update --help`);
+        const eq = t.indexOf("=");
+        const name = eq === -1 ? t.slice(2) : t.slice(2, eq);
+        if (!KNOWN_FLAGS.has(name))
+            throw new Error(`unknown flag --${name}. Known flags: --check, --to, --auto`);
+        if (name === "check" || name === "background") {
+            flags.set(name, "");
+            continue;
+        }
+        const value = eq === -1 ? args[++i] : t.slice(eq + 1);
+        if (value === undefined || value === "")
+            throw new Error(`--${name} needs a value`);
+        flags.set(name, value);
+    }
+    return flags;
+}
+/** The `--check` line after a failed install (#3325): whether — and when — it is tried again. */
+function nextAttemptLine(state, latest, mode, running, now) {
+    if (mode === AUTOUPDATE_OFF)
+        return "→ automatic updates are off here; `datum update` retries now";
+    if (mode === AUTOUPDATE_MIN_ONLY && compareVersions(running, latest.minVersion) >= 0) {
+        return "→ min-only: no automatic attempt above the server's minimum; `datum update` retries now";
+    }
+    if (state.failedInstall?.integrity !== latest.package?.integrity) {
+        return "→ the server now serves a rebuilt bundle: the next automatic attempt tries it, `datum update` now";
+    }
+    const until = installDeferredUntil(state, latest, now);
+    return until !== null
+        ? `→ next automatic attempt after ${describeWhen(until, now)}; \`datum update\` retries now`
+        : "→ the next automatic attempt may run now";
+}
+/** The `--check` line for the server's bundle signature (#2612) — checkable without downloading it. */
+function describeSignature(version, pkg, rootKeys) {
+    try {
+        // Only these two fields: anything else a server put in `package` (a
+        // `version`, say) must not stand in for the release it announced.
+        const check = checkBundleSignature({ version, integrity: pkg.integrity, signature: pkg.signature }, { rootKeys, packageNames: CLI_PACKAGE_NAMES });
+        return check.signed ? `signed by Datum (root key ${check.rootKeyId})` : `UNSIGNED — ${check.reason}`;
+    }
+    catch (err) {
+        return `INVALID — ${err.message}; this CLI will not install it`;
+    }
+}
+export async function runUpdate(ctx, io) {
+    let flags;
+    try {
+        flags = parse(ctx.args);
+    }
+    catch (err) {
+        io.err.write(`datum: ${err.message}\n`);
+        return 2;
+    }
+    const background = flags.has("background");
+    const packaged = isPackagedInstall(ctx.entryDir);
+    // Handed over by the npm-installed launcher? Then THAT is "the package".
+    const packageVersion = ctx.env[ENV_LAUNCHER_VERSION] ?? ctx.ownVersion;
+    if (flags.has("auto")) {
+        const v = flags.get("auto").toLowerCase();
+        if (v !== "on" && v !== "off") {
+            io.err.write("datum: --auto takes on or off\n");
+            return 2;
+        }
+        writeState(ctx.paths, { autoUpdate: v === "on" });
+        io.out.write(`Automatic updates ${v === "on" ? "enabled" : "disabled"} for this user (${ctx.paths.stateFile}).\n`);
+        const effective = autoUpdateMode(ctx.env, readState(ctx.paths));
+        if ((v === "on") !== (effective !== AUTOUPDATE_OFF)) {
+            io.out.write(`Note: the environment overrides it here — the effective mode is \`${effective}\`.\n`);
+        }
+        return 0;
+    }
+    if (flags.has("to")) {
+        const target = flags.get("to");
+        try {
+            if (target === "package") {
+                clearCurrent(ctx.paths);
+                io.out.write(`The next \`datum\` runs the npm-installed package (${packageVersion}).\n`);
+            }
+            else {
+                switchTo(ctx.paths, target);
+                io.out.write(`The next \`datum\` runs ${target}.\n`);
+                if (compareVersions(target, packageVersion) < 0) {
+                    io.out.write(`Note: ${target} is older than the npm-installed package (${packageVersion}), which wins — use \`--to package\` or reinstall the package at ${target}.\n`);
+                }
+            }
+            return 0;
+        }
+        catch (err) {
+            io.err.write(`datum: ${err.message}\n`);
+            return 1;
+        }
+    }
+    if (!packaged) {
+        if (!background) {
+            io.err.write(`datum: this CLI runs from a repository build (the app image or a checkout), which never updates itself — only the published ${CLI_PACKAGE_NAME} package does.\n`);
+        }
+        return background ? 0 : 1;
+    }
+    if (!ctx.baseUrl) {
+        if (!background) {
+            io.err.write("datum: no server to ask — pass --base-url, set DATUM_BASE_URL or run `datum login` first\n");
+        }
+        return background ? 0 : 2;
+    }
+    if (flags.has("check")) {
+        const state = readState(ctx.paths);
+        const lines = [
+            `running:   ${effectiveVersion(ctx.ownVersion, ctx.paths)}`,
+            `package:   ${packageVersion} (npm-installed)`,
+            `pointer:   ${readCurrent(ctx.paths) ?? "(none)"}`,
+            `installed: ${installedVersions(ctx.paths).join(", ") || "(none)"}`,
+            `mode:      ${autoUpdateMode(ctx.env, state)}`,
+        ];
+        try {
+            const latest = await fetchLatest(ctx.baseUrl, ctx.deps.fetch, 10_000);
+            writeState(ctx.paths, { lastCheckAt: new Date(ctx.deps.now()).toISOString(), latest, lastError: undefined });
+            lines.push(`server:    ${latest.version} (minimum ${latest.minVersion}${latest.package ? "" : ", no bundle to install"}) at ${ctx.baseUrl}`);
+            if (latest.package)
+                lines.push(`signature: ${describeSignature(latest.version, latest.package, ctx.deps.rootKeys)}`);
+            const running = effectiveVersion(ctx.ownVersion, ctx.paths);
+            lines.push(compareVersions(latest.version, running) > 0
+                ? `→ ${latest.version} is available: run \`datum update\``
+                : "→ up to date");
+            const failed = state.failedInstall;
+            if (failed && latest.package && failed.version === latest.version && compareVersions(latest.version, running) > 0) {
+                lines.push(`failed:    installing ${failed.version} failed ${failed.count}× (last ${failed.at}) — ${failed.error}`, nextAttemptLine(state, latest, autoUpdateMode(ctx.env, state), running, ctx.deps.now()));
+            }
+        }
+        catch (err) {
+            lines.push(`server:    unreachable — ${err.message}`);
+        }
+        io.out.write(`${lines.join("\n")}\n`);
+        return 0;
+    }
+    try {
+        const before = effectiveVersion(ctx.ownVersion, ctx.paths);
+        const outcome = await checkForUpdate({
+            baseUrl: ctx.baseUrl,
+            ownVersion: ctx.ownVersion,
+            paths: ctx.paths,
+            deps: ctx.deps,
+            // A person asking for the update now gets an attempt now (#3325).
+            ignoreBackoff: !background,
+        });
+        if (background)
+            return 0;
+        if (outcome.installed) {
+            io.out.write(`Updated ${before} → ${outcome.installed}. The next \`datum\` runs it.\n`);
+            const notice = takeNotice(ctx.paths);
+            if (notice)
+                io.err.write(notice);
+        }
+        else if (!outcome.latest.package && compareVersions(outcome.latest.version, before) > 0) {
+            io.out.write(`The server runs ${outcome.latest.version} but carries no CLI bundle — install it with \`npm i -g ${CLI_PACKAGE_NAME}@${outcome.latest.version}\`.\n`);
+        }
+        else {
+            io.out.write(`datum ${before} is up to date (the server runs ${outcome.latest.version}).\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (!background)
+            io.err.write(`datum: the update failed — ${oneLine(err.message)}\n`);
+        return background ? 0 : 1;
+    }
+}
+//# sourceMappingURL=updateCommand.js.map