makefx 0.1.0 → 0.1.1

package/README.md

@@ -1,62 +1,34 @@
-# Make Effects
+# makefx
 
-Make Effects is an AI media production workspace at
-[makefx.app](https://makefx.app) where people and agents can generate, refine,
-track, and hand off production assets across images, audio, and video.
+Command-line interface for [Make Effects](https://makefx.app), an AI media
+production workspace for game assets, production references, and handoff files.
 
-The hosted app is the source of truth for spaces, assets, variants, prompts,
-recipes, lineage, collaboration state, and stored media. The `makefx` CLI lets
-local agents, scripts, and developers drive that same production graph from the
-command line: start generation jobs, watch progress, download outputs, inspect
-results, curate variants, and export production handoff data.
+`makefx` lets local developers, scripts, and coding agents create and manage
+website-backed assets from the terminal: generate images, audio, and video;
+upload local media; inspect variants; download outputs; watch real-time space
+events; and export production records.
 
-## What You Can Build With It
-
-- Generate images, audio, and video through website-backed jobs.
-- Track every result as an asset variant with prompt, provider metadata, and
-  lineage.
-- Refine an existing variant or derive new assets from references.
-- Upload local media into a collaborative space so generated and hand-made
-  assets live together.
-- Let automation agents use the CLI as a stable control surface instead of
-  touching database or storage internals.
-- Export production records for downstream render, game, or editorial tools.
-
-## Features
-
-- **Authentication**: Google OAuth with JWT tokens, OIDC-compliant
-- **Dual-Worker Architecture**: Separate workers for HTTP/frontend and media generation
-- **React 19 Frontend**: Vite, TanStack Router, Zustand, CSS Modules
-- **D1 Database**: SQLite with migrations and Kysely query builder
-- **R2 Media Storage**: Durable media artifacts for generated and uploaded files
-- **Dependency Injection**: InversifyJS for clean architecture
-- **Make Effects CLI**: Command-line access through the `makefx` package and command
-- **TypeScript**: End-to-end type safety
-
-## CLI Quick Start
-
-Install the CLI from npm:
+## Install
 
 ```bash
 npm install -g makefx
+makefx --version
 ```
 
-Authenticate with the hosted app:
+Requirements:
 
-```bash
-makefx login
-```
+- Node.js 20 or newer
+- A Make Effects account at https://makefx.app
+
+The npm package installs a bundled executable and does not declare runtime
+dependencies.
 
-Create a space or bind an existing website space to the current directory:
+## Quick Start
 
 ```bash
+makefx login
 makefx spaces create "My Game Assets" --init
-makefx init --space YOUR_SPACE_ID
-```
-
-Generate media and download completed outputs:
 
-```bash
 makefx generate "A cozy pixel-art market background" \
   --name "Market Background" \
   --type scene \
@@ -73,113 +45,133 @@ makefx video generate "A looping idle animation for a tiny robot" \
   -o video/robot-idle.mp4
 ```
 
-Inspect and reuse tracked results:
+## Authentication
 
 ```bash
-makefx assets
-makefx assets show ASSET_ID --json
-makefx assets download VARIANT_ID -o references/variant.png
-makefx listen --space YOUR_SPACE_ID
-makefx rotation --variant VARIANT_ID --config 8-directional
-makefx tileset "cohesive grass, path, and stone terrain tiles" --type terrain --grid 3x3
+makefx login
+makefx logout
 ```
 
-Use run manifests for debugging agent workflows:
+`login` opens a browser-based sign-in flow and stores CLI credentials in the
+user config directory. Credentials are separate from project bindings and are
+not written into your repository.
+
+## Project Binding
+
+Bind the current directory to a Make Effects space:
 
 ```bash
-makefx runs --debug
-makefx runs show --latest --debug --json
+makefx init --space YOUR_SPACE_ID
 ```
 
+This writes `.inventory/config.json` with the target environment and space ID.
+It does not store assets, prompts, media files, provider keys, or auth tokens.
+Inside an initialized project, commands can omit `--space` and `--env`.
+
 The CLI defaults to production at `https://makefx.app`. Use `--env stage` for
-staging or `--local` for a local development server.
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `makefx login` | Authenticate with makefx.app |
-| `makefx spaces` | List, view, or create collaborative spaces |
-| `makefx init` | Bind the current directory to a website space |
-| `makefx generate` | Generate a new image asset |
-| `makefx refine` | Refine an existing image variant |
-| `makefx derive` | Create a new image asset from variant IDs or local refs |
-| `makefx batch` | Generate multiple images and write a debug run manifest |
-| `makefx audio` | Generate speech, dialogue, music, or sound effects |
-| `makefx video` | Generate, refine, or derive video assets |
-| `makefx upload` | Upload local image, audio, or video files |
-| `makefx assets` | List, show, download, rename, delete, and set active assets |
-| `makefx variants` | Retry, star, rate, or delete variants |
-| `makefx rotation` | Generate and monitor rotation views from a completed image variant |
-| `makefx tileset` | Generate and monitor consistent tile sets |
-| `makefx listen` | Stream real-time space events |
-| `makefx productions` | Place, list, and export production records |
-| `makefx runs` | Inspect debug-only local generation manifests |
-
-See [docs/cli.md](./docs/cli.md) and
-[docs/cli-generation.md](./docs/cli-generation.md) for the full command guide.
-
-## Local Development
+staging, or `--local` for a local development server.
 
-```bash
-# Install dependencies
-pnpm install
+## Common Workflows
+
+Inspect and download tracked assets:
 
-# Set up environment
-cp .env.example .env
-# Edit .env with your Google OAuth credentials
+```bash
+makefx assets
+makefx assets show ASSET_ID --json
+makefx assets download VARIANT_ID -o references/variant.png
+```
 
-# Initialize local database
-pnpm run db:migrate
+Upload local media:
 
-# Start development
-pnpm run dev
+```bash
+makefx upload hero.png --name "Hero Character" --type character
+makefx upload theme.mp3 --name "Theme Music" --type audio
+makefx upload cutscene.mp4 --name "Cutscene" --type video
 ```
 
-Access at http://localhost:3001/
+Refine or derive from references:
 
-## Developer Commands
+```bash
+makefx refine --variant VARIANT_ID "make it evening, with warmer lights" \
+  -o art/market-evening.png
 
-| Command | Description |
-|---------|-------------|
-| `pnpm run dev` | Start local development (frontend + worker) |
-| `pnpm run build:cli` | Build `dist/cli/makefx.mjs` |
-| `pnpm run cli:dev -- --help` | Run the CLI from TypeScript sources |
-| `pnpm run db:migrate` | Apply database migrations locally |
-| `pnpm test` | Run tests |
-| `pnpm run typecheck` | TypeScript type checking |
-| `pnpm run lint` | ESLint |
-| `pnpm run deploy:stage` | Deploy to stage environment |
-| `pnpm run deploy:production` | Deploy to production |
+makefx derive \
+  --refs CHARACTER_VARIANT_ID,BACKGROUND_VARIANT_ID \
+  --name "Hero In Market" \
+  --type scene \
+  "Place the hero naturally in the market" \
+  -o art/hero-market.png
+```
 
-## Project Structure
+Create production helpers:
 
+```bash
+makefx rotation --variant VARIANT_ID --config 8-directional
+makefx tileset "grass and stone path tiles" --type terrain --grid 3x3
+makefx productions export --production-id trailer-01 -o handoff/scenes.args
 ```
-src/
-├── backend/       # API routes, services, middleware
-├── frontend/      # React application
-├── dao/           # Data access layer
-├── db/migrations/ # SQL migrations
-├── cli/           # CLI tool
-└── worker/        # Cloudflare Worker entry points
+
+Watch real-time space activity:
+
+```bash
+makefx listen --space YOUR_SPACE_ID
+makefx listen --space YOUR_SPACE_ID --json
 ```
 
-## Documentation
+## Agent And Script Usage
 
-- [docs/cli.md](./docs/cli.md) - complete CLI reference
-- [docs/cli-generation.md](./docs/cli-generation.md) - agent-oriented media generation flows
-- [docs/architecture.md](./docs/architecture.md) - system architecture
-- [PRD.md](./PRD.md) - product requirements and core concepts
+Many commands support `--json` for stable machine-readable output. Use JSON
+outputs for automation instead of parsing human-readable tables.
 
-## Tech Stack
+```bash
+makefx spaces create "Agent Test Space" --init --json
+makefx assets --json
+makefx runs show --latest --debug --json
+```
 
-- **Runtime**: Cloudflare Workers
-- **Database**: Cloudflare D1 (SQLite)
-- **Frontend**: React 19, Vite, Zustand
-- **Backend**: Hono, InversifyJS, Kysely
-- **Auth**: Google OAuth, JWT (jose)
-- **Testing**: Node.js test runner
+Debug run manifests are local troubleshooting traces for generation commands:
 
-## License
+```bash
+makefx runs --debug
+makefx runs show --latest --debug
+```
 
-MIT
+The website remains the source of truth for spaces, assets, variants, recipes,
+lineage, and stored media.
+
+## Command Groups
+
+| Command | Purpose |
+|---------|---------|
+| `login`, `logout` | Manage CLI authentication |
+| `spaces`, `init` | Create spaces and bind local projects |
+| `generate`, `refine`, `derive`, `batch` | Generate image assets |
+| `audio` | Generate speech, dialogue, music, and sound effects |
+| `video` | Generate, refine, and derive video assets |
+| `upload` | Upload local image, audio, or video files |
+| `assets`, `variants` | Inspect, download, curate, retry, or delete outputs |
+| `rotation`, `tileset` | Generate game-ready reference sets |
+| `productions` | Place and export production handoff records |
+| `listen` | Stream real-time space events |
+| `runs` | Inspect local debug manifests |
+| `billing` | Inspect billing sync and operational status |
+
+Run `makefx --help` or `makefx help <command>` for command-specific options.
+
+## Troubleshooting
+
+- If a command says you are not authenticated, run `makefx login`.
+- If a command cannot find a space, run `makefx init --space YOUR_SPACE_ID` or
+  pass `--space YOUR_SPACE_ID`.
+- If a generation command times out after creating a variant, resume with
+  `--follow VARIANT_ID` and the same output path.
+- If automation needs stable output, add `--json` where supported.
+
+## Links
+
+- App: https://makefx.app
+- CLI docs: https://makefx.app/docs/cli
+- Media generation guide: https://makefx.app/docs/media-playbooks
+- Source: https://github.com/krasnoperov/inventory
+
+Version: 0.1.1

package/{dist/cli/makefx.mjs → makefx.mjs}

@@ -488,6 +488,9 @@ async function handleBilling(parsed) {
 		case "ops-check":
 			await handleBillingOpsCheck(env);
 			break;
+		case "reconcile":
+			await handleBillingReconcile(env, parsed);
+			break;
 		case "retry":
 		case "retry-failed":
 			await handleBillingRetry(env);
@@ -510,6 +513,7 @@ Usage:
 Subcommands:
   status           Show sync status (pending, failed, synced events)
   check            Run operational checks for workers, Polar meters, and sync health
+  reconcile        Compare local billable usage with Polar usage for one user
   retry-failed     Reset failed events for retry (next cron will sync them)
 
 Options:
@@ -520,6 +524,7 @@ Examples:
   makefx billing status                    Show production sync status
   makefx billing status --env stage        Show stage sync status
   makefx billing check                     Run production operational checks
+  makefx billing reconcile --user-id 42    Reconcile one customer usage period
   makefx billing retry-failed              Reset failed events for retry
 
 Note: Requires login first. Run 'makefx login' to authenticate.
@@ -656,15 +661,35 @@ function secondsSummary(seconds) {
 }
 async function handleBillingOpsCheck(env) {
 	console.log(`Running billing operational checks for ${env}...\n`);
-	const [workerChecks, billingChecks] = await Promise.all([checkWorkerHealth(env), callBillingApi(env, "/api/billing/operational-checks")]);
+	const workerChecks = await checkWorkerHealth(env);
 	console.log("=== Billing Operational Checks ===\n");
 	console.log("Workers:");
 	for (const check of workerChecks) console.log(`  ${statusLabel(check.status)} ${check.name.padEnd(12)} ${check.message}`);
+	let billingChecks;
+	try {
+		billingChecks = await callBillingApi(env, "/api/billing/operational-checks");
+	} catch (error) {
+		console.log("\nAuthenticated billing checks:");
+		console.log(`  ${statusLabel("critical")} ${error instanceof Error ? error.message : String(error)}`);
+		console.log("\nResult: CRITICAL - billing checks need an authenticated admin session.");
+		process$1.exitCode = 1;
+		return;
+	}
 	const meterCheck = billingChecks.checks.polarMeters;
 	console.log("\nPolar meters:");
 	console.log(`  ${statusLabel(meterCheck.status)} configured=${meterCheck.configured} active=${meterCheck.active.length} expected=${meterCheck.expected.length}`);
 	if (meterCheck.error) console.log(`  Error: ${meterCheck.error}`);
 	if (meterCheck.missing.length > 0) console.log(`  Missing: ${meterCheck.missing.join(", ")}`);
+	if (meterCheck.invalid.length > 0) console.log(`  Invalid: ${meterCheck.invalid.map((meter) => meter.name).join(", ")}`);
+	const productCheck = billingChecks.checks.paidGenerationProduct;
+	if (productCheck) {
+		console.log("\nPaid generation product:");
+		const product = productCheck.product;
+		console.log(`  ${statusLabel(productCheck.status)} configured=${product?.configured ?? false} recurring=${product?.isRecurring ?? "n/a"} archived=${product?.isArchived ?? "n/a"}`);
+		if (product?.productId) console.log(`  Product: ${product.productId}${product.name ? ` (${product.name})` : ""}`);
+		console.log(`  Metered prices: ${product?.meteredPriceMeters.length ?? 0}/${productCheck.expectedMeteredPriceMeters.length}`);
+		if (productCheck.missingMeteredPriceMeters.length > 0) console.log(`  Missing metered prices: ${productCheck.missingMeteredPriceMeters.join(", ")}`);
+	}
 	const syncCheck = billingChecks.checks.syncHealth;
 	console.log("\nSync health:");
 	console.log(`  ${statusLabel(syncCheck.status)} pending=${syncCheck.events.pending} failed=${syncCheck.events.failed} synced=${syncCheck.events.synced}`);
@@ -677,11 +702,38 @@ async function handleBillingOpsCheck(env) {
 	const hasCriticalBilling = billingChecks.status === "critical";
 	const hasWarning = workerChecks.some((check) => check.status === "warning") || billingChecks.status === "warning";
 	if (hasCriticalWorker || hasCriticalBilling) {
-		console.log("\nResult: CRITICAL - production billing operations need attention.");
+		console.log("\nResult: CRITICAL - billing operations need attention.");
 		process$1.exitCode = 1;
 	} else if (hasWarning) console.log("\nResult: WARNING - billing is operational but has lag or cleanup work.");
 	else console.log("\nResult: OK - billing workers, meters, and sync health are ready.");
 }
+async function handleBillingReconcile(env, parsed) {
+	const userId = parsed.options["user-id"] || parsed.options.userId || parsed.positionals[1];
+	if (!userId) {
+		console.error("Missing user id. Use: makefx billing reconcile --user-id <id>");
+		process$1.exitCode = 1;
+		return;
+	}
+	console.log(`Reconciling billing usage for user ${userId} in ${env}...\n`);
+	try {
+		const data = await callBillingApi(env, `/api/billing/reconcile?user_id=${encodeURIComponent(userId)}`);
+		console.log("=== Billing Reconciliation ===\n");
+		console.log(`Period: ${data.period.start} → ${data.period.end}`);
+		console.log(`Status: ${data.status.toUpperCase()}`);
+		console.log("\nMeters:");
+		for (const meter of data.meters) {
+			const marker = meter.matched ? "OK      " : "MISMATCH";
+			console.log(`  ${marker} ${meter.name.padEnd(22)} local=${meter.local} polar=${meter.polar} delta=${meter.delta}`);
+		}
+		if (data.mismatches.length > 0) {
+			console.log("\nMismatched meters need sync/retry investigation before billing is considered reconciled.");
+			process$1.exitCode = 1;
+		}
+	} catch (error) {
+		console.error("Reconciliation failed:", error instanceof Error ? error.message : error);
+		process$1.exitCode = 1;
+	}
+}
 async function handleBillingRetry(env) {
 	console.log(`Resetting failed events for ${env}...\n`);
 	try {
@@ -23513,7 +23565,7 @@ Options:
 }
 //#endregion
 //#region src/cli/index.ts
-var CLI_VERSION = "0.1.0+8fe959ed0b7b";
+var CLI_VERSION = "0.1.1+fe5390f9d193";
 async function main() {
 	const [, , command, ...args] = process$1.argv;
 	if (command === "--version" || command === "version") {
@@ -23702,6 +23754,8 @@ Project:
 Billing (Polar.sh):
   billing status               Show sync status (pending, failed, synced events)
   billing check                Run operational checks for workers, meters, and sync health
+  billing reconcile --user-id <id>
+                               Compare local billable usage with Polar usage
   billing retry-failed         Retry all failed events
 
 Spaces:
@@ -23800,6 +23854,7 @@ Usage:
 Subcommands:
   status           Show sync status (pending, failed, synced events)
   check            Run operational checks for workers, Polar meters, and sync health
+  reconcile        Compare local billable usage with Polar usage for one user
   retry-failed     Reset failed events for retry (next cron will sync them)
 
 Options:

package/package.json

@@ -1,111 +1,25 @@
 {
   "name": "makefx",
-  "version": "0.1.0",
-  "description": "Make Effects CLI and Cloudflare app for AI-assisted game asset production.",
+  "version": "0.1.1",
+  "description": "Command-line interface for AI-assisted game asset production with Make Effects.",
+  "license": "MIT",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krasnoperov/inventory.git"
+  },
   "bin": {
-    "makefx": "dist/cli/makefx.mjs"
+    "makefx": "./makefx.mjs"
   },
   "files": [
-    "dist/cli/makefx.mjs",
+    "makefx.mjs",
     "README.md"
   ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
   "publishConfig": {
     "access": "public"
-  },
-  "packageManager": "pnpm@11.1.1",
-  "scripts": {
-    "bootstrap:worktree": "node ./scripts/bootstrap-worktree.mjs",
-    "dev": "CLOUDFLARE_VITE_CONFIG_PATH=wrangler.dev.toml vite",
-    "build": "vite build && pnpm run package:frontend-start && pnpm run build:cli",
-    "package:frontend-start": "node scripts/package-frontend-start.mjs",
-    "build:cli": "node scripts/build-cli.mjs",
-    "deploy": "pnpm run build && pnpm exec wrangler deploy",
-    "deploy:production": "CLOUDFLARE_ENV=production pnpm run build && pnpm exec wrangler deploy --env production",
-    "deploy:stage": "pnpm run build && pnpm exec wrangler deploy",
-    "test": "node ./scripts/run-node-tests.mjs",
-    "test:components": "playwright test --config playwright.component.config.ts",
-    "test:components:ci": "node ./scripts/run-component-ci.mjs",
-    "test:e2e:media-foundation": "pnpm run build && node scripts/e2e-media-foundation.mjs",
-    "test:e2e:cli-forge": "pnpm run build && node scripts/e2e-cli-forge.mjs",
-    "auth:session-state": "node scripts/auth/mint-session.mjs",
-    "lint": "oxlint --config .oxlintrc.json src scripts && pnpm d1:guard && pnpm lint:tokens",
-    "lint:tokens": "pnpm tokens:guard && pnpm tokens:snapshot:check && pnpm tokens:roundtrip",
-    "tokens:guard": "node scripts/check-design-tokens.mjs",
-    "tokens:snapshot": "node scripts/snapshot-design-tokens.mjs",
-    "tokens:snapshot:check": "node scripts/snapshot-design-tokens.mjs --check",
-    "tokens:roundtrip": "node scripts/generate-css-from-tokens.mjs --check",
-    "d1:guard": "node scripts/check-no-d1-transactions.mjs",
-    "typecheck": "tsc --noEmit",
-    "ci:pre-push": "pnpm run typecheck && pnpm run lint && pnpm run build && pnpm test --test-reporter=dot && pnpm run test:components:ci",
-    "db:migrate": "node --import @swc-node/register/esm-register scripts/db-migrate.ts",
-    "db:migrate:stage": "node --import @swc-node/register/esm-register scripts/db-migrate.ts stage remote",
-    "db:migrate:production": "node --import @swc-node/register/esm-register scripts/db-migrate.ts production remote",
-    "cli": "node dist/cli/makefx.mjs",
-    "cli:dev": "node --import @swc-node/register/esm-register src/cli/index.ts",
-    "stories": "LADLE=true ladle serve",
-    "stories:build": "LADLE=true ladle build",
-    "style-reference": "node scripts/export-style-reference.mjs",
-    "style-reference:rebuild": "node scripts/export-style-reference.mjs --rebuild"
-  },
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.71.0",
-    "@google/genai": "^1.30.0",
-    "@hono/zod-openapi": "^1.4.0",
-    "@openai/agents": "^0.3.3",
-    "@polar-sh/sdk": "^0.41.5",
-    "@react-oauth/google": "^0.12.2",
-    "@tanstack/react-query": "^5.90.11",
-    "@tanstack/react-router": "^1.170.15",
-    "@tanstack/react-start": "^1.168.25",
-    "@types/d3-force": "^3.0.10",
-    "@types/dagre": "^0.7.53",
-    "@xyflow/react": "^12.9.3",
-    "better-sqlite3": "^12.4.6",
-    "d3-force": "^3.0.0",
-    "dagre": "^0.8.5",
-    "dotenv": "^17.2.3",
-    "fflate": "^0.8.2",
-    "hono": "^4.10.6",
-    "inversify": "^7.10.4",
-    "jose": "^6.1.2",
-    "kysely": "^0.28.8",
-    "kysely-d1": "^0.4.0",
-    "nanoid": "^5.1.11",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "react-markdown": "^10.1.0",
-    "reflect-metadata": "^0.2.2",
-    "remark-gfm": "^4.0.1",
-    "standardwebhooks": "1.0.0",
-    "uuid": "^13.0.0",
-    "ws": "^8.21.0",
-    "zod": "^4.4.3",
-    "zustand": "^5.0.8"
-  },
-  "devDependencies": {
-    "@cloudflare/ai": "^1.2.2",
-    "@cloudflare/vite-plugin": "^1.39.0",
-    "@cloudflare/workers-types": "4.20260317.1",
-    "@csstools/postcss-light-dark-function": "^3.0.0",
-    "@ladle/react": "^5.1.1",
-    "@playwright/test": "^1.59.1",
-    "@swc-node/register": "^1.11.1",
-    "@tanstack/router-plugin": "^1.168.18",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
-    "@types/ws": "^8.18.1",
-    "@vitejs/plugin-react": "^5.1.1",
-    "express": "^5.1.0",
-    "oxlint": "1.67.0",
-    "postcss": "^8.5.6",
-    "postcss-preset-env": "^10.4.0",
-    "prettier": "^3.6.2",
-    "rollup-plugin-visualizer": "^6.0.5",
-    "typescript": "^5.9.3",
-    "vite": "^8.0.14",
-    "wrangler": "4.95.0"
   }
 }