@agent-journal/cli 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# @agent-journal/cli
+
+NPM wrapper for the Agent Journal member CLI.
+
+## Install
+
+```bash
+npm install -g @agent-journal/cli
+```
+
+If global install fails with `EACCES`, configure npm to use a user-owned prefix
+and add its `bin` directory to `PATH` instead of using `sudo npm install`.
+
+## Use
+
+```bash
+agent-journal init --base-url https://your-service.example <invite_code>
+agent-journal start
+agent-journal status
+```
+
+For local debugging:
+
+```bash
+agent-journal run
+```
+
+To stop and remove the background agent:
+
+```bash
+agent-journal uninstall
+```
+
+After a manual npm upgrade, restart the background service so it points at the
+managed runtime under `~/.agent-journal/current`:
+
+```bash
+npm install -g @agent-journal/cli@latest
+agent-journal restart
+agent-journal status
+```
+
+To check or apply a managed update published by the service:
+
+```bash
+agent-journal update --check
+agent-journal update --apply
+```
+
+`--apply` downloads the selected artifact, verifies its sha256 and signature,
+installs it under `~/.agent-journal/versions/<version>`, switches
+`~/.agent-journal/current`, and restarts the managed service when one is
+installed.
+
+If the service rollout has auto apply disabled, the background agent records the
+available update and `agent-journal status` prints the target version; it will
+not download or execute the artifact until `agent-journal update --apply` runs.
+
+## Publishing
+
+The production publishing path is GitHub Actions Trusted Publishing. Configure
+the npm package trusted publisher with:
+
+- Package: `@agent-journal/cli`
+- Publisher: GitHub Actions
+- Repository owner: `Bloomingg`
+- Repository name: `agent-journal`
+- Workflow filename: `client-release.yml`
+- Environment: empty unless the workflow is later bound to a GitHub environment
+
+Then manually run the `Client Release` workflow. The workflow builds the
+vendored binaries with `AGENT_JOURNAL_UPDATE_PUBLIC_KEY`, generates the signed
+service release manifest with `AGENT_JOURNAL_UPDATE_PRIVATE_KEY_PEM`, publishes
+the npm package through OIDC, uploads update artifacts, and registers release
+metadata with the Agent Journal service.
+
+The npm package is only the first-install bootstrap. After CI registers a
+release, use Admin Release Center to publish it to `dev`, `beta`, or `stable`
+and control rollout percentage, auto apply, forced update, pause, and rollback.
+
+Local commands are for dry-run checks only:
+
+```bash
+set -a
+source ../../.env.update-signing
+set +a
+unset AGENT_JOURNAL_UPDATE_PRIVATE_KEY_PEM
+npm test
+npm run build:binaries
+npm pack --dry-run --ignore-scripts
+```
+
+The npm package only needs `AGENT_JOURNAL_UPDATE_PUBLIC_KEY`. Do not leave
+`AGENT_JOURNAL_UPDATE_PRIVATE_KEY_PEM` in the environment for `npm publish`;
+the private key is only needed when generating a signed service release
+manifest.
+
+The CI publish step uses `npm publish --ignore-scripts` after a single explicit
+binary build. This avoids `prepack` rebuilding the npm package binaries after
+the signed release artifacts have already been generated.
+
+Set `AGENT_JOURNAL_UPDATE_PUBLIC_KEY` when building release binaries so managed
+updates can verify service-provided artifact signatures:
+
+```bash
+AGENT_JOURNAL_UPDATE_PUBLIC_KEY="<base64-ed25519-public-key>" npm run build:binaries
+```
+
+After uploading the built binaries to release storage, generate the service
+registration payload:
+
+```bash
+set -a
+source ../../.env.update-signing
+set +a
+AGENT_JOURNAL_ARTIFACT_BASE_URL="https://updates.example.com/agent-journal/0.1.0" \
+npm run release:manifest
+```
+
+The generated `dist/release-manifest.json` can be POSTed to
+`/api/v1/admin/client-releases`. The script also copies release-named binaries
+to `dist/artifacts/` so CI can upload files whose names match the manifest URLs.
+
+`release:local` runs the npm wrapper tests, builds the vendored binaries with package version, git commit, UTC build time metadata, and the optional update public key, then performs an `npm pack --dry-run`.
+
+The package includes binaries for macOS arm64/x64, Windows x64, and Linux x64.

package/bin/agent-journal.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { targetFor } = require("../lib/platform");
+
+function binaryPath() {
+  const target = targetFor();
+  return path.join(__dirname, "..", "vendor", target.dir, target.exe);
+}
+
+const bin = binaryPath();
+if (!fs.existsSync(bin)) {
+  console.error(`agent-journal binary is missing for ${process.platform}/${process.arch}: ${bin}`);
+  console.error("Reinstall the npm package, or run `npm run build:binaries` before packing/publishing.");
+  process.exit(1);
+}
+
+const result = spawnSync(bin, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+  windowsHide: false
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+process.exit(result.status ?? 1);

package/lib/platform.js

@@ -0,0 +1,22 @@
+"use strict";
+
+const SUPPORTED_TARGETS = [
+  { nodePlatform: "darwin", nodeArch: "arm64", goos: "darwin", goarch: "arm64", dir: "darwin-arm64", exe: "agent-journal" },
+  { nodePlatform: "darwin", nodeArch: "x64", goos: "darwin", goarch: "amd64", dir: "darwin-x64", exe: "agent-journal" },
+  { nodePlatform: "win32", nodeArch: "x64", goos: "windows", goarch: "amd64", dir: "win32-x64", exe: "agent-journal.exe" },
+  { nodePlatform: "linux", nodeArch: "x64", goos: "linux", goarch: "amd64", dir: "linux-x64", exe: "agent-journal" }
+];
+
+function targetFor(platform = process.platform, arch = process.arch) {
+  const target = SUPPORTED_TARGETS.find((item) => item.nodePlatform === platform && item.nodeArch === arch);
+  if (!target) {
+    const supported = SUPPORTED_TARGETS.map((item) => `${item.nodePlatform}/${item.nodeArch}`).join(", ");
+    throw new Error(`Unsupported platform ${platform}/${arch}. Supported: ${supported}`);
+  }
+  return target;
+}
+
+module.exports = {
+  SUPPORTED_TARGETS,
+  targetFor
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@agent-journal/cli",
+  "version": "0.1.0",
+  "description": "Agent Journal member CLI",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bloomingg/agent-journal.git",
+    "directory": "packages/agent-journal"
+  },
+  "bin": {
+    "agent-journal": "bin/agent-journal.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/postinstall.js",
+    "vendor/",
+    "README.md"
+  ],
+  "scripts": {
+    "build:binaries": "node scripts/build-binaries.js",
+    "prepack": "npm test && npm run build:binaries",
+    "postinstall": "node scripts/postinstall.js",
+    "prepack:dry-run": "npm pack --dry-run --ignore-scripts",
+    "release:manifest": "node scripts/create-release-manifest.js",
+    "release:local": "npm test && npm run build:binaries && npm pack --dry-run --ignore-scripts",
+    "test": "node scripts/test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { targetFor } = require("../lib/platform");
+
+const target = targetFor();
+const bin = path.join(__dirname, "..", "vendor", target.dir, target.exe);
+
+if (!fs.existsSync(bin)) {
+  console.error(`Missing agent-journal binary for ${process.platform}/${process.arch}.`);
+  console.error(`Expected: ${bin}`);
+  console.error("This package must be published after running `npm run build:binaries`.");
+  process.exit(1);
+}
+
+if (process.platform !== "win32") {
+  fs.chmodSync(bin, 0o755);
+}
+
+const home = os.homedir();
+const launchAgent = path.join(home, "Library", "LaunchAgents", "com.agent-journal.agent.plist");
+if (process.platform === "darwin" && fs.existsSync(launchAgent)) {
+  console.warn("agent-journal: background service detected.");
+  console.warn("agent-journal: run `agent-journal restart` after this npm update to switch the service to the installed version.");
+}
+if (process.platform === "win32") {
+  console.warn("agent-journal: if the background task is already installed, run `agent-journal restart` after this npm update.");
+}