@allowance/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allowance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# allowance
+
+`allowance` is a human-first CLI for Allowance purchase workflows.
+
+It uses an `ak_...` connection token at runtime and stores credentials in the OS keychain.
+Runtime actions are token-scoped, so requests/allowances are visible to the token session that created them.
+
+## Install
+
+Primary (npm):
+
+```bash
+npm install -g @allowance/cli
+```
+
+This npm package exposes the `allowance` command and bootstraps the Python runtime automatically.
+Prerequisite: Python 3.12+ on PATH (`python3` or `python`).
+
+Secondary (pipx):
+
+```bash
+pipx install allowance
+```
+
+Local source install:
+
+```bash
+pipx install .
+```
+
+Local development:
+
+```bash
+uv sync --dev
+uv run allowance --help
+```
+
+## Publish to npm
+
+This repo supports npm publishing through GitHub Actions.
+
+### One-time setup
+
+1. Create the npm scope/org `@allowance` and grant maintainer access.
+2. Create an npm automation token with publish permission.
+3. Add it as a GitHub repository secret:
+   - name: `NPM_TOKEN`
+   - value: npm token string
+
+### Release flow
+
+1. Bump `version` in `package.json`.
+2. Commit and push `main`.
+3. Tag and push a npm release tag:
+
+```bash
+git tag npm-v0.1.1
+git push origin npm-v0.1.1
+```
+
+4. GitHub Action `.github/workflows/publish-npm.yml` runs and publishes `@allowance/cli`.
+
+After workflow success, users can install with:
+
+```bash
+npm install -g @allowance/cli
+```
+
+## Publish to PyPI
+
+This repo also supports PyPI publishing for `pipx` users.
+
+### One-time setup
+
+1. Create a PyPI account for the maintainer/org.
+2. Create a project-scoped API token in PyPI.
+3. Add the token as a GitHub repository secret:
+   - name: `PYPI_API_TOKEN`
+   - value: `pypi-...`
+
+### Release flow
+
+1. Bump `version` in `pyproject.toml`.
+2. Commit and push `main`.
+3. Tag and push a version tag:
+
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+4. GitHub Action `.github/workflows/publish-pypi.yml` runs:
+   - lint/type/test
+   - build wheels/sdist
+   - publish to PyPI
+
+## Fast Purchase Path (Recommended)
+
+Use this flow for fastest agent and customer experience:
+
+1. Authenticate once for the session.
+2. Create a request with clear merchant + reason + cap amount.
+3. Ask customer to approve immediately in app.
+4. Poll until approved.
+5. Issue card only when checkout is ready.
+6. Complete checkout.
+7. Report purchase outcome immediately (`success` or `failed`).
+8. If failed and still active, re-issue and retry within policy limits.
+
+Example:
+
+```bash
+allowance auth login --email you@example.com
+allowance requests create --cents 5000 --merchant "Ticketmaster" --reason "2 tickets under $50"
+allowance requests poll <request_id>
+allowance cards issue <allowance_id> --expected-cents 4500
+allowance cards report <allowance_id> <attempt_id> --status success --charged-cents 4380
+```
+
+## Auth
+
+Login bootstraps via OTP, then mints and stores a connection token:
+
+```bash
+allowance auth login --email you@example.com
+```
+
+If already logged in, login exits with:
+
+`Already logged in as <email>. Run allowance auth logout to switch accounts.`
+
+Status command:
+
+```bash
+allowance auth status
+```
+
+Logout command (revokes remote token and clears keychain):
+
+```bash
+allowance auth logout
+```
+
+## Command Reference
+
+All commands output JSON by default. Use `--pretty` for formatted JSON.
+
+| Command | What It Does | Use When |
+|---|---|---|
+| `allowance auth login --email <email>` | Signs in via OTP bootstrap and stores token in keychain | Starting a session |
+| `allowance auth status` | Shows whether CLI is logged in and which account/token prefix | Preflight checks |
+| `allowance auth logout` | Revokes token and clears local credentials | End of session/security cleanup |
+| `allowance requests create --cents ... --merchant ... --reason ... [--currency] [--expires-at]` | Creates a pending allowance request | You need user approval before spending |
+| `allowance requests list` | Lists requests created by this token session | Find recent request IDs |
+| `allowance requests get <request_id>` | Fetches full request detail | Inspect request state/details |
+| `allowance requests poll <request_id>` | Returns current request status and `allowance_id` when approved | Waiting on user approval |
+| `allowance requests cancel <request_id>` | Cancels a still-pending request | User changed mind / no longer needed |
+| `allowance cards issue <allowance_id> --expected-cents <int>` | Issues checkout card for one purchase attempt | Approval exists and checkout is ready |
+| `allowance cards attempts <allowance_id>` | Lists purchase attempts for that allowance | Audit/retry decisions |
+| `allowance cards report <allowance_id> <attempt_id> --status success\\|failed ...` | Finalizes attempt result and updates allowance state | Immediately after checkout attempt |
+| `allowance allowances list` | Lists allowances visible to current token | Find/manage active allowances |
+| `allowance allowances get <allowance_id>` | Gets one allowance snapshot | Verify state/retry budget |
+| `allowance allowances pause <allowance_id>` | Pauses spending on allowance | Temporary stop needed |
+| `allowance allowances revoke <allowance_id>` | Permanently revokes allowance | Final stop / cleanup |
+
+`allowance allowances unpause` is intentionally not exposed in this CLI.
+
+## Agent + Customer Experience Guidelines
+
+1. Request only when purchase intent and budget are clear.
+2. Use merchant/reason text the customer can quickly recognize in approval UI.
+3. After `requests create`, immediately provide request summary and ask customer to approve.
+4. Poll with short intervals, but keep customer informed instead of silently looping.
+5. Issue card only at the final checkout step to reduce stale credential windows.
+6. Always call `cards report` right after checkout outcome.
+7. Never echo PAN/CVV unless customer explicitly asks.
+
+## Error Handling
+
+| Status | Meaning | Typical Action |
+|---|---|---|
+| `401` | Auth invalid/expired | Re-login |
+| `403` | Not allowed for this actor | Use correct actor/flow |
+| `404` | Not found or out-of-scope token access | Verify IDs and token session |
+| `409` | State conflict (not active, retry exhausted, etc.) | Inspect current resource state and adjust |
+| `503` | Upstream issuer/provider unavailable | Retry later or fail gracefully |
+
+## Global Flags
+
+- `--api-base-url` to target another environment for one invocation
+- `--pretty` for formatted JSON output
+
+Example:
+
+```bash
+allowance --api-base-url http://127.0.0.1:8000 --pretty allowances list
+```
+
+## Configuration
+
+- `ALLOWANCE_API_BASE_URL` (default: `https://allowance-api.fly.dev`)
+- `ALLOWANCE_HTTP_TIMEOUT_SECONDS` (default: `20`)
+- `ALLOWANCE_CLI_KEYCHAIN_SERVICE` (optional keychain namespace override)
+- `ALLOWANCE_CLI_KEYCHAIN_ACCOUNT` (optional keychain account override)
+
+## Tests
+
+```bash
+./scripts/test_unit.sh
+./scripts/test_smoke.sh
+./scripts/test_all.sh
+```

package/bin/allowance.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+'use strict';
+
+const childProcess = require('node:child_process');
+
+const packageJson = require('../package.json');
+const { allowanceExecutablePath, ensureRuntime } = require('../lib/runtime');
+
+function main() {
+  const pypiPackage = process.env.ALLOWANCE_PYPI_PACKAGE || 'allowance';
+  ensureRuntime({
+    version: packageJson.version,
+    pypiPackage,
+    skipInstall: false,
+  });
+
+  const result = childProcess.spawnSync(allowanceExecutablePath(), process.argv.slice(2), {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+try {
+  main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[allowance] ${message}`);
+  process.exit(1);
+}

package/lib/runtime.js

@@ -0,0 +1,181 @@
+'use strict';
+
+const childProcess = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PYTHON_MIN_MAJOR = 3;
+const PYTHON_MIN_MINOR = 12;
+
+function runtimeRoot() {
+  return process.env.ALLOWANCE_NPM_RUNTIME_DIR || path.join(os.homedir(), '.allowance-cli-runtime');
+}
+
+function venvDir() {
+  return path.join(runtimeRoot(), 'venv');
+}
+
+function stateFilePath() {
+  return path.join(runtimeRoot(), 'state.json');
+}
+
+function venvPythonPath() {
+  if (process.platform === 'win32') {
+    return path.join(venvDir(), 'Scripts', 'python.exe');
+  }
+  return path.join(venvDir(), 'bin', 'python');
+}
+
+function allowanceExecutablePath() {
+  if (process.platform === 'win32') {
+    return path.join(venvDir(), 'Scripts', 'allowance.exe');
+  }
+  return path.join(venvDir(), 'bin', 'allowance');
+}
+
+function parseVersion(versionText) {
+  const match = versionText.match(/(\d+)\.(\d+)/);
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+  };
+}
+
+function pythonVersionSupported(version) {
+  if (!version) {
+    return false;
+  }
+  if (version.major > PYTHON_MIN_MAJOR) {
+    return true;
+  }
+  if (version.major < PYTHON_MIN_MAJOR) {
+    return false;
+  }
+  return version.minor >= PYTHON_MIN_MINOR;
+}
+
+function detectPythonCommand() {
+  const candidates = [];
+
+  if (process.env.ALLOWANCE_PYTHON) {
+    candidates.push([process.env.ALLOWANCE_PYTHON]);
+  }
+
+  if (process.platform === 'win32') {
+    candidates.push(['py', '-3']);
+  }
+
+  candidates.push(['python3.13']);
+  candidates.push(['python3.12']);
+  candidates.push(['python3']);
+  candidates.push(['python']);
+
+  for (const candidate of candidates) {
+    const check = childProcess.spawnSync(
+      candidate[0],
+      candidate.slice(1).concat(['-c', 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")']),
+      { encoding: 'utf8' },
+    );
+
+    if (check.error || check.status !== 0) {
+      continue;
+    }
+
+    const parsed = parseVersion((check.stdout || '').trim());
+    if (pythonVersionSupported(parsed)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function runOrThrow(command, args, options = {}) {
+  const result = childProcess.spawnSync(command, args, {
+    stdio: options.quiet ? 'pipe' : 'inherit',
+    encoding: 'utf8',
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    if (options.quiet) {
+      if (result.stdout) {
+        process.stderr.write(result.stdout);
+      }
+      if (result.stderr) {
+        process.stderr.write(result.stderr);
+      }
+    }
+    throw new Error(`Command failed: ${command} ${args.join(' ')}`);
+  }
+}
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(stateFilePath(), 'utf8'));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeState(state) {
+  fs.mkdirSync(runtimeRoot(), { recursive: true });
+  fs.writeFileSync(stateFilePath(), JSON.stringify(state, null, 2));
+}
+
+function ensureVenv(pythonCommand) {
+  const pythonPath = venvPythonPath();
+  if (fs.existsSync(pythonPath)) {
+    return;
+  }
+
+  fs.mkdirSync(runtimeRoot(), { recursive: true });
+  runOrThrow(pythonCommand[0], pythonCommand.slice(1).concat(['-m', 'venv', venvDir()]));
+}
+
+function installPinnedPackage(targetSpec) {
+  const pythonPath = venvPythonPath();
+  runOrThrow(pythonPath, ['-m', 'pip', 'install', '--upgrade', 'pip'], { quiet: true });
+  runOrThrow(pythonPath, ['-m', 'pip', 'install', targetSpec], { quiet: true });
+}
+
+function ensureRuntime(options) {
+  const targetSpec = `${options.pypiPackage}==${options.version}`;
+  const currentState = readState();
+
+  if (fs.existsSync(allowanceExecutablePath()) && currentState && currentState.targetSpec === targetSpec) {
+    return;
+  }
+
+  const pythonCommand = detectPythonCommand();
+  if (!pythonCommand) {
+    throw new Error(
+      'Python 3.12+ is required. Install a supported Python or set ALLOWANCE_PYTHON.',
+    );
+  }
+
+  ensureVenv(pythonCommand);
+
+  if (!options.skipInstall) {
+    console.error('[allowance] Bootstrapping runtime (one-time setup)...');
+    installPinnedPackage(targetSpec);
+    writeState({
+      targetSpec,
+      installedAt: new Date().toISOString(),
+    });
+  }
+
+  if (!fs.existsSync(allowanceExecutablePath())) {
+    throw new Error('Bootstrap failed: allowance executable was not installed in the runtime venv.');
+  }
+}
+
+module.exports = {
+  allowanceExecutablePath,
+  ensureRuntime,
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@allowance/cli",
+  "version": "0.1.0",
+  "description": "Allowance CLI wrapper package for npm global installs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dasmer/allowance-cli.git"
+  },
+  "homepage": "https://github.com/dasmer/allowance-cli",
+  "bugs": {
+    "url": "https://github.com/dasmer/allowance-cli/issues"
+  },
+  "keywords": [
+    "allowance",
+    "cli",
+    "payments",
+    "agents"
+  ],
+  "bin": {
+    "allowance": "bin/allowance.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "scripts/npm-postinstall.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "postinstall": "node scripts/npm-postinstall.js"
+  }
+}

package/scripts/npm-postinstall.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const packageJson = require('../package.json');
+const { ensureRuntime } = require('../lib/runtime');
+
+function main() {
+  const pypiPackage = process.env.ALLOWANCE_PYPI_PACKAGE || 'allowance';
+  ensureRuntime({
+    version: packageJson.version,
+    pypiPackage,
+    skipInstall: false,
+  });
+}
+
+try {
+  main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.warn(`[allowance] Postinstall bootstrap skipped: ${message}`);
+  console.warn('[allowance] The runtime will bootstrap on first command execution.');
+}