agentflex 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# agentflex
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**An animated card of your coding-agent week, in one command.**
+
+![agentflex card animation (fictional data)](https://raw.githubusercontent.com/corral-dev/agentflex/main/docs/demo.gif)
+
+```bash
+npx agentflex
+```
+
+No install, no account, no upload. It reads the local histories of Claude Code, Codex, OpenCode and Pi, adds up the last 7 days, and plays the card in your terminal. Press `s` to save a 1200×630 PNG for posting, `r` to replay, `q` to quit.
+
+Also works with `pnpm dlx agentflex` and `bunx agentflex`.
+
+## What the card shows
+
+- **Tokens** for the period, as each assistant recorded them (cache reads included).
+- **Sessions**, **tokens per day** and **peak parallel sessions** (the most agent sessions active at the same moment).
+- **Agent share** across Claude Code, Codex, OpenCode and Pi.
+- **Activity** by weekday and hour, with your busiest hour.
+
+## Options
+
+```bash
+npx agentflex --month        # last 30 days
+npx agentflex --all          # all retained history
+npx agentflex --png week.png # write the image and exit
+npx agentflex --json         # print the numbers as JSON
+npx agentflex --no-anim      # final card without animation
+```
+
+## Fast
+
+The default 7-day card is computed in well under a second on a heavy-use machine (about 900 MB of history): histories are read in parallel, pruned to the period, and only the fields that matter are decoded. The parsing engine is [SessKit](https://github.com/x0c/sesskit)'s native `sesskit-stats` crate, checked session by session against SessKit's reference implementation.
+
+## Platforms
+
+macOS (Apple silicon, Intel), Linux (x64, arm64) and Windows (x64, arm64). Histories are found in each assistant's standard location; `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_DATA_HOME`, `OPENCODE_DB`, `PI_CODING_AGENT_DIR` and `PI_CODING_AGENT_SESSION_DIR` are honored.
+
+## Privacy
+
+Everything stays on your machine. The card shows totals only: no prompts, file names, project names or paths.
+
+## From the makers of Corral
+
+agentflex comes from [Corral](https://github.com/corral-dev/corral), a terminal home for all your coding-agent sessions: see who needs you, run agents side by side, and pick up from your phone. Corral users can also run `corral flex`.
+
+## License
+
+MIT. The PNG export embeds a subset of the [Spleen](https://github.com/fcambus/spleen) bitmap font (BSD-2-Clause, see https://github.com/corral-dev/agentflex/blob/main/assets/SPLEEN-LICENSE.txt).

package/bin/agentflex.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// agentflex npm launcher.
+//
+// The real binary lives in a per-platform optional dependency
+// (agentflex-darwin-arm64, agentflex-linux-x64, ...). This script resolves
+// the matching package at *run* time and spawns the binary, so no
+// postinstall step is needed (pnpm 10 and Bun block postinstall scripts by
+// default, which is why install-time downloading is avoided).
+//
+// Reused pattern: one main package plus per-platform optional packages with
+// `os`/`cpu` constraints, as in `@biomejs/biome` (CJS launcher resolving
+// `<pkg>/biome[.exe]` and spawning it with stdio "inherit") and `ccusage`
+// (explicit unsupported-platform error, exit-code forwarding, re-raising the
+// child's termination signal, repairing the run-time executable bit). Like
+// Biome the launcher is CJS with `spawnSync`, so `require.resolve` works
+// verbatim on npm, pnpm and Bun; like ccusage a killed child re-raises the
+// same signal on this process instead of silently mapping it to exit 0.
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const { chmodSync, statSync } = require("node:fs");
+
+// Test-only overrides (documented for launcher verification, e.g.
+// `AGENTFLEX_PLATFORM=freebsd AGENTFLEX_ARCH=x64 npx agentflex` must print
+// the unsupported-platform line below and exit 1).
+const OVERRIDE_PLATFORM = process.env.AGENTFLEX_PLATFORM || undefined;
+const OVERRIDE_ARCH = process.env.AGENTFLEX_ARCH || undefined;
+
+// platform -> arch -> { package, file }
+const PLATFORMS = {
+  darwin: {
+    arm64: { package: "agentflex-darwin-arm64", file: "bin/agentflex" },
+    x64: { package: "agentflex-darwin-x64", file: "bin/agentflex" },
+  },
+  linux: {
+    arm64: { package: "agentflex-linux-arm64", file: "bin/agentflex" },
+    x64: { package: "agentflex-linux-x64", file: "bin/agentflex" },
+  },
+  win32: {
+    arm64: { package: "agentflex-win32-arm64", file: "bin/agentflex.exe" },
+    x64: { package: "agentflex-win32-x64", file: "bin/agentflex.exe" },
+  },
+};
+
+const SUPPORTED = "darwin (arm64, x64), linux (x64, arm64), win32 (x64, arm64)";
+
+function currentTarget() {
+  return {
+    platform: OVERRIDE_PLATFORM || process.platform,
+    arch: OVERRIDE_ARCH || process.arch,
+  };
+}
+
+// Every failure is one clear English line on stderr, exit code 1.
+function fail(message) {
+  process.stderr.write(`agentflex: ${message}\n`);
+  process.exit(1);
+}
+
+function ensureExecutable(path, platform) {
+  if (platform === "win32") {
+    return;
+  }
+  try {
+    if ((statSync(path).mode & 0o111) !== 0) {
+      return;
+    }
+    chmodSync(path, 0o755);
+  } catch {
+    // Leave the error to spawn reporting below.
+  }
+}
+
+function main() {
+  const { platform, arch } = currentTarget();
+  const target = `${platform}-${arch}`;
+  const entry = Object.prototype.hasOwnProperty.call(PLATFORMS, platform)
+    ? PLATFORMS[platform][arch]
+    : undefined;
+  if (!entry) {
+    fail(`unsupported platform ${target}; supported platforms: ${SUPPORTED}.`);
+  }
+  let binary;
+  try {
+    binary = require.resolve(`${entry.package}/${entry.file}`);
+  } catch {
+    fail(
+      `package "${entry.package}" for ${target} is not installed (reinstall agentflex with optional dependencies enabled); supported platforms: ${SUPPORTED}.`
+    );
+  }
+  ensureExecutable(binary, platform);
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+  if (result.error) {
+    fail(`cannot run "${entry.package}" for ${target}: ${result.error.message}.`);
+  }
+  if (result.signal) {
+    // Re-raise so callers observe the same termination signal.
+    try {
+      process.kill(process.pid, result.signal);
+    } catch {
+      // Fall through to exit(1) when re-raising is impossible.
+    }
+    process.exit(1);
+  }
+  process.exit(result.status === null || result.status === undefined ? 1 : result.status);
+}
+
+main();

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "agentflex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Animated, shareable card of your coding-agent week (terminal + PNG export)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/corral-dev/agentflex.git"
+  },
+  "homepage": "https://github.com/corral-dev/agentflex#readme",
+  "bin": {
+    "agentflex": "./bin/agentflex.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "optionalDependencies": {
+    "agentflex-darwin-arm64": "0.1.0",
+    "agentflex-darwin-x64": "0.1.0",
+    "agentflex-linux-arm64": "0.1.0",
+    "agentflex-linux-x64": "0.1.0",
+    "agentflex-win32-arm64": "0.1.0",
+    "agentflex-win32-x64": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}