balladeer 0.0.3

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Balladeer
+
+All rights reserved.
+
+This package reserves the "balladeer" package name and points at the official
+installer. It grants no rights to Balladeer's software or services. Use of the
+Balladeer service is governed by Balladeer's Terms of Service.

package/README.md

@@ -0,0 +1,77 @@
+# Balladeer
+
+Balladeer makes your AI agents work like they have been on your team for years. It is
+decision memory for engineering teams and their agents: it captures the decisions your
+team makes while building (the question, the call, the why, the rejected options) and
+returns them at the moment they matter: before an agent builds, when a choice comes up,
+and when a new plan contradicts a settled call.
+
+A real serving from Balladeer's own brain (2026-07-14, trimmed). The agent asked before
+touching a webhook receiver, and the team's settled call came back with its certainty
+and its why:
+
+```text
+⟢ balladeer · 2 decisions for "Add a rate limiter to the webhook receiver…"
+
+decision decision_1a4cdf8b-f92: The remote-MCP per-org RPM cap is enforced FLEET-WIDE
+  via a shared DB counter (mcp_rate_counters: one row per (org, minute bucket), single
+  atomic INSERT ... ON CONFLICT ... SET hits=hits+1 RETURNING), replacing the per-process
+  Map that would have enforced N x the limit across N machines. […]
+  certainty: confirmed by a human
+  question it settles: How should the remote-MCP rate limit be enforced across multiple
+  Fly machines, and which parts of the guard should stay per-process?
+```
+
+When the agent then makes a new call of its own, the decision is recorded back
+(unconfirmed until a human confirms it) and surfaces to every future session that
+touches it.
+
+## What it does mechanically
+
+- Your agent gains three habits over MCP: `get_context` before non-trivial work,
+  `consult` at a choice, `propose_decision` when a call gets made. Every decision
+  carries its certainty (human-confirmed vs machine-captured) and its receipts.
+- Your team's decisions live on a shared central server; the `balladeer` CLI and the
+  hosted MCP connector read from and write to it directly, with no local database to
+  manage.
+- Humans stay in charge: `balladeer recent` and the status line show what accumulated;
+  confirm or dismiss from the terminal. `balladeer uninstall` removes everything the
+  setup installed (your data directory is backed up, not deleted).
+- Decisions cluster into initiatives: cite a decision id in the PR body that delivers
+  it and its definition of done checks off on merge, so initiative progress is derived
+  from merged work, not status updates.
+
+## Install
+
+```sh
+npm install -g balladeer
+balladeer
+```
+
+This package is a thin installer. On your consent (one prompt; `--yes` to skip), it
+downloads the current Balladeer client from `get.balladeer.ai`, verifies the published
+sha256 checksum, and installs the verified file globally, replacing this installer with
+the real client (the everyday `balladeer` CLI).
+Equivalent, without npm:
+
+```sh
+curl -fsSL https://get.balladeer.ai | sh
+```
+
+Then pair the machine to your team:
+
+```sh
+balladeer login
+```
+
+You need a Balladeer workspace to pair with; create one at
+[app.balladeer.ai](https://app.balladeer.ai).
+
+Flags: `--yes` installs without prompting; `--download-only` fetches and verifies the
+client tarball and prints its path without installing.
+
+The client is served from Balladeer's own infrastructure so every install gets the
+current build; the client package will publish here directly once self-serve install
+stabilizes.
+
+Copyright (c) 2026 Balladeer. All rights reserved.

package/bin/balladeer.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Bootstrapper for the Balladeer client (npm name: balladeer).
+ *
+ * This package is not the client; it installs it. On consent it downloads the
+ * current client tarball from Balladeer's central installer endpoints, verifies
+ * the published sha256, and `npm install -g`s the verified file, which replaces
+ * this package in place (the client ships under the same package name).
+ *
+ * Flags: --yes/-y skip the prompt; --download-only fetch + verify, print the path.
+ */
+const { createHash } = require("node:crypto");
+const { mkdtempSync, writeFileSync, rmSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+const { spawnSync } = require("node:child_process");
+const readline = require("node:readline");
+
+const BASE = process.env.BALLADEER_INSTALL_BASE ?? "https://get.balladeer.ai";
+const TGZ_URL = `${BASE}/install/client.tgz`;
+const SHA_URL = `${BASE}/install/client.tgz.sha256`;
+
+const args = process.argv.slice(2);
+const yes = args.includes("--yes") || args.includes("-y");
+const downloadOnly = args.includes("--download-only");
+
+function fail(msg, code = 1) {
+  console.error(msg);
+  process.exit(code);
+}
+
+async function fetchBytes(url) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) {
+    fail(
+      `error: ${url} answered ${res.status}` +
+        (res.status === 503 ? " (the client artifact is not available on the server yet)" : ""),
+    );
+  }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+async function main() {
+  console.error(
+    `balladeer: this npm package is the installer, not the client.\n` +
+      `It downloads the current Balladeer client from ${BASE}, verifies its\n` +
+      `sha256 checksum, and installs it globally (replacing this package).\n`,
+  );
+
+  if (!yes && !downloadOnly) {
+    if (!process.stdin.isTTY) {
+      fail(
+        `Non-interactive shell: re-run with --yes to install, or use the script installer:\n\n` +
+          `  curl -fsSL ${BASE} | sh\n`,
+      );
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    const answer = await new Promise((res) => rl.question("Install the Balladeer client now? [Y/n] ", res));
+    rl.close();
+    if (answer.trim() !== "" && !/^y(es)?$/i.test(answer.trim())) fail("Nothing installed.");
+  }
+
+  console.error(`downloading ${TGZ_URL} ...`);
+  const [tgz, shaFile] = await Promise.all([fetchBytes(TGZ_URL), fetchBytes(SHA_URL)]);
+  const expected = shaFile.toString("utf8").trim().split(/\s+/)[0];
+  const actual = createHash("sha256").update(tgz).digest("hex");
+  if (!/^[0-9a-f]{64}$/.test(expected) || expected !== actual) {
+    fail(
+      `error: checksum mismatch; refusing to install a tampered download.\n` +
+        `  expected ${expected}\n  actual   ${actual}`,
+    );
+  }
+  console.error(`checksum OK (sha256 ${actual.slice(0, 16)}...)`);
+
+  // A private mkdtemp dir, not a predictable name in the shared tmpdir: the same posture as
+  // the script installer's `mktemp -d`, so nothing can pre-place a file/symlink at the path.
+  const dir = mkdtempSync(join(tmpdir(), "balladeer-"));
+  const file = join(dir, "balladeer-client.tgz");
+  writeFileSync(file, tgz);
+  if (downloadOnly) {
+    console.log(file);
+    return;
+  }
+
+  // --ignore-scripts: the client has no install hooks, and this keeps a hostile tarball from
+  // running code at install time (the same flag the script installer passes).
+  const r = spawnSync("npm", ["install", "-g", "--ignore-scripts", file], {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {}
+  if (r.status !== 0) {
+    fail(`error: npm install -g failed (exit ${r.status ?? "?"}). Fix the npm error above and re-run \`balladeer\`.`, r.status ?? 1);
+  }
+
+  // Plain `balladeer login` (the client defaults to hosted central). BASE is the INSTALL host
+  // (get.balladeer.ai), an alias that exists only for downloading — teaching it as --server
+  // would store it as the machine's permanent server URL. A custom BALLADEER_INSTALL_BASE
+  // means a self-hosted deploy whose central URL this bootstrapper cannot derive, so point at
+  // the flag rather than silently teaching the hosted default.
+  const pairHint =
+    BASE === "https://get.balladeer.ai"
+      ? "balladeer login"
+      : "balladeer login --server <your central server URL>";
+  console.error(
+    `\n✓ Balladeer client installed.\n\n` +
+      `  next   ${pairHint}     # approve in your browser; no token to copy\n` +
+      `  then   your coding agent gains get_context / consult / propose_decision\n` +
+      `  agent  or let your agent finish the wiring: paste into it -> Read ${BASE}/agent and follow it.\n\n` +
+      `  no workspace yet? create one at https://app.balladeer.ai`,
+  );
+}
+
+main().catch((err) => fail(`error: ${err?.message ?? err}`));

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "balladeer",
+  "version": "0.0.3",
+  "description": "Installer for the Balladeer client (decision memory for engineering teams and their AI agents): downloads the sha256-verified client from get.balladeer.ai and installs it globally.",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://balladeer.ai",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "balladeer": "bin/balladeer.js"
+  },
+  "files": [
+    "bin",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}