ai-garcon 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,130 @@
+# ai-garcon
+
+Observability for coding agents. One tiny local proxy sits in front of Claude Code, Codex,
+OpenClaw, Hermes or any compatible client, records what every call cost in tokens, and shows
+it in one dashboard, across accounts, tools and, with sync on, every machine you work from.
+Requests and replies are forwarded unchanged; prompts, replies and keys are never stored.
+
+Documentation: https://asieke.github.io/garcon/ · Source: https://github.com/asieke/garcon
+
+## Install and set up this machine
+
+```sh
+npm install -g ai-garcon@latest
+garcon setup
+```
+
+macOS and Linux, x64 and arm64; Node 18+ is needed to run the npm command.
+`setup` starts Garcon at login and verifies http://127.0.0.1:4141. Open the printed
+Settings link, choose your harness and account label, and copy its configuration.
+Restart the harness, send one short request, and check Logs. Existing usage and sync
+settings are preserved when setup is rerun. Sync is optional.
+
+To try it without a global install: `npx ai-garcon@latest` runs in the foreground.
+For containers or Linux without a systemd user session, run `garcon` in one terminal
+and `garcon setup --no-service` in another. A custom foreground address works with
+`garcon -listen 127.0.0.1:4242` and `garcon setup --no-service --url http://127.0.0.1:4242`.
+
+If installation fails with EACCES, use a Node version manager or a user-owned npm
+prefix ([npm's instructions](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/)).
+Run setup as your normal user. If `garcon` is not found, ensure `$(npm prefix -g)/bin`
+is on PATH and restart your shell. `type -a garcon` finds competing source/npm installs.
+
+## Update
+
+```sh
+garcon update
+```
+
+This updates the owning global npm installation, refreshes an installed service,
+and waits for its new version to answer. Without a service, it tells you how to start
+one or restart your foreground process. Usage, settings and device identity are kept.
+Updating briefly restarts the proxy; finish active agent requests first.
+For an older Garcon without `update`, use:
+
+```sh
+npm install -g ai-garcon@latest
+garcon service restart
+garcon doctor --wait 10s
+```
+
+The service uses its own executable at `~/.local/share/garcon/bin/garcon`, so changing
+Node versions or clearing an npx cache cannot remove it. After changing Node versions,
+reinstall the npm command in the new environment and run `garcon setup`.
+
+## Check or remove an installation
+
+```sh
+garcon doctor                     # reachability, versions, first request, sync progress/errors
+garcon service status
+garcon service uninstall          # stop autostart; keep usage and settings
+npm uninstall -g ai-garcon
+```
+
+Restore each harness's original base URL/provider before removing the proxy, so your
+tools can keep connecting. Linux service logs: `journalctl --user -u garcon`.
+macOS logs: `~/Library/Logs/garcon.log`.
+
+## Point an agent at it
+
+```sh
+# Claude Code
+ANTHROPIC_BASE_URL=http://127.0.0.1:4141/claude/me@example.com \
+_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1 claude
+```
+
+Codex, OpenClaw, Hermes and anything OpenAI- or Anthropic-compatible: Settings → Connect a
+harness generates the exact configuration, or see the
+[docs](https://asieke.github.io/garcon/connect.html). Make one short call and the row appears
+in Logs.
+
+
+## Sync across devices
+
+Optional: local recording works without Supabase. First, run `garcon setup` on each
+machine. Give each machine a distinct device name in Settings → Sync. Use the same
+project on every machine; do not copy `sync.json` or another machine's data directory,
+because that would duplicate its identity.
+
+**First machine, browser path (no Supabase CLI required):**
+
+1. Create or choose a Supabase project in your own account.
+2. Run `garcon connect-supabase --print-sql` and paste the output into that project's SQL Editor.
+3. In Garcon Settings → Sync, enter a device name, project URL and secret (`sb_secret_`) key
+   from Project Settings → API Keys. Enable sync and Save. Garcon verifies table access
+   before saving. Keep this project key in your password manager for the next machine.
+
+**First machine, automated CLI path:** install the [Supabase CLI](https://supabase.com/docs/guides/cli),
+run `supabase login`, then explicitly choose project creation or reuse:
+
+```sh
+garcon connect-supabase --create-project --name "work laptop"
+# Or apply the schema to an existing project:
+garcon connect-supabase --project-ref <ref> --name "work laptop"
+```
+
+Creation checks CLI capabilities first; `--org-id` and `--region` choose where to create
+it. Review your organization's project limits and plan in Supabase. If a later step fails,
+reuse the printed project ref instead of creating another project.
+
+**Subsequent machines:** open Settings → Sync, paste the same URL and key, choose a new
+device name, enable and Save. No CLI, new project, or SQL needed. For a headless machine,
+read the key from a password manager or protected file rather than putting it in shell history:
+
+```sh
+garcon connect-supabase --name "home desktop" \
+  --project-url https://<ref>.supabase.co --key-stdin < /path/to/protected-key-file
+# Or with the Supabase CLI already logged in:
+garcon connect-supabase --name "home desktop" --project-ref <ref> --skip-schema
+garcon doctor
+```
+
+Save verifies table access; syncing happens in the background. Within about a minute,
+Settings → Sync should show the other devices. `garcon doctor` reports pending uploads
+and the latest sync errors. First enable uploads existing local history.
+
+Only device, time, harness, account, provider, model, status, latency and token counts
+are synced. Prompts and replies are not recorded. The project secret key can access other
+project data too: use a dedicated project and share the key only with your own trusted
+machines. It is stored in `~/.config/garcon/config.json` with mode 0600. Turning sync off
+stops push/pull while retaining local usage. See the [sync guide](https://asieke.github.io/garcon/sync.html).

package/bin/check-package.js

@@ -0,0 +1,13 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+for (const target of ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64']) {
+ const binary = path.join(__dirname, '..', 'dist', target, 'garcon');
+ try {
+  const stat = fs.statSync(binary);
+  if (!stat.isFile() || stat.size < 1024 || !(stat.mode & 0o111)) throw new Error('invalid executable');
+ } catch {
+  console.error(`Missing or invalid ${target} binary. Build all targets with scripts/release.sh VERSION --dry-run before packing or publishing.`);
+  process.exit(1);
+ }
+}

package/bin/garcon.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 'use strict';
 const { spawnSync } = require('node:child_process');
-const { pkg, binaryPath } = require('./resolve.js');
+const { target, binaryPath } = require('./resolve.js');
+if (process.argv[2] === 'update') process.exit(require('./update.js').update(process.argv.slice(3)));
 const bin = binaryPath();
 if (!bin) {
-	console.error(`ai-garcon: no prebuilt binary for ${process.platform}-${process.arch} (package ${pkg}).`);
+	console.error(`ai-garcon: binary missing for ${target}. Supported: linux/darwin on x64/arm64. Reinstall with npm install -g ai-garcon@latest.`);
 	console.error('Build from source instead: https://github.com/asieke/garcon');
 	process.exit(1);
 }

package/bin/resolve.js

@@ -1,11 +1,10 @@
-// Locate the prebuilt binary for this platform, installed as an optional dependency.
+// The package ships one static binary per platform under dist/<os>-<arch>/garcon.
 'use strict';
-const pkg = `ai-garcon-${process.platform}-${process.arch}`;
+const path = require('node:path');
+const fs = require('node:fs');
+const target = `${process.platform}-${process.arch}`;
 function binaryPath() {
-	try {
-		return require.resolve(`${pkg}/bin/garcon`);
-	} catch {
-		return null;
-	}
+	const p = path.join(__dirname, '..', 'dist', target, 'garcon');
+	return fs.existsSync(p) ? p : null;
 }
-module.exports = { pkg, binaryPath };
+module.exports = { target, binaryPath };

package/bin/update.js

@@ -0,0 +1,42 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { spawnSync } = require('node:child_process');
+
+// Only update the global installation that owns this shim, never an unrelated prefix.
+function globalPrefix(packageDir) {
+ const suffix = path.join('lib', 'node_modules', 'ai-garcon');
+ return packageDir.endsWith(path.sep + suffix) ? packageDir.slice(0, -suffix.length - 1) || '/' : null;
+}
+function update(args, { packageDir = path.resolve(__dirname, '..'), spawn = spawnSync,
+ exists = fs.existsSync, home = os.homedir(), platform = process.platform } = {}) {
+ if (args.length) {
+  console.log('Usage: garcon update\nUpdates this global npm installation, refreshes an installed service, and checks its version.');
+  return args.length === 1 && ['--help', '-h'].includes(args[0]) ? 0 : 2;
+ }
+ const prefix = globalPrefix(packageDir);
+ if (!prefix) {
+  console.error('For npx: run npx ai-garcon@latest setup. For a local dependency: npm install ai-garcon@latest, then npx garcon setup.');
+  return 1;
+ }
+ function run(bin, argv) {
+  const r = spawn(bin, argv, { stdio: 'inherit' });
+  if (r.error) { console.error(r.error.message); return 1; }
+  return r.status ?? 1;
+ }
+ console.log(`Updating ai-garcon in ${prefix}…`);
+ const status = run('npm', ['install', '--global', '--prefix', prefix, 'ai-garcon@latest']);
+ if (status) {
+  console.error('Update failed. For EACCES, use a user-owned npm prefix: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/');
+  return status;
+ }
+ const shim = path.join(packageDir, 'bin/garcon.js');
+ if (!exists(shim)) { console.error('Package shim missing after update; reinstall ai-garcon.'); return 1; }
+ const unit = platform === 'darwin' ? path.join(home, 'Library/LaunchAgents/dev.garcon.plist') : path.join(home, '.config/systemd/user/garcon.service');
+ if (!exists(unit)) { console.log('Updated. Run garcon setup to start the service, or restart your foreground Garcon.'); return 0; }
+ const restart = run(process.execPath, [shim, 'service', 'restart']);
+ if (restart) return restart;
+ return run(process.execPath, [shim, 'doctor', '--wait', '10s']);
+}
+module.exports = { update, globalPrefix };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-garcon",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Observability for coding agents: a local pass-through proxy that records what Claude Code, Codex and other agents spend in tokens, with a dashboard and optional cross-device sync.",
   "keywords": [
     "claude-code",
@@ -20,18 +20,23 @@
     "garcon": "bin/garcon.js"
   },
   "files": [
-    "bin"
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
   ],
-  "scripts": {
-    "postinstall": "node bin/postinstall.js"
-  },
   "engines": {
     "node": ">=18"
   },
-  "optionalDependencies": {
-    "ai-garcon-linux-x64": "0.1.0",
-    "ai-garcon-linux-arm64": "0.1.0",
-    "ai-garcon-darwin-x64": "0.1.0",
-    "ai-garcon-darwin-arm64": "0.1.0"
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepack": "node bin/check-package.js"
   }
 }

package/bin/postinstall.js

@@ -1,12 +0,0 @@
-// After an install or upgrade, restart a running garcon service so it picks up the new
-// binary. `garcon service restart` is a no-op when no service is installed, and any
-// failure here must never fail the npm install itself.
-'use strict';
-const { spawnSync } = require('node:child_process');
-const { binaryPath } = require('./resolve.js');
-const bin = binaryPath();
-if (bin) {
-	try {
-		spawnSync(bin, ['service', 'restart'], { stdio: 'inherit' });
-	} catch {}
-}