@miketromba/ploof 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Tromba
+
+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,278 @@
+<p align="center">
+  <strong>Ploof</strong>
+</p>
+
+<p align="center">
+  AI asset generation from the command line.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@miketromba/ploof"><img src="https://img.shields.io/npm/v/@miketromba/ploof" alt="npm version" /></a>
+  <a href="https://github.com/miketromba/ploof/actions/workflows/ci.yml"><img src="https://github.com/miketromba/ploof/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/miketromba/ploof/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@miketromba/ploof" alt="license" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node version" />
+</p>
+
+Ploof is a CLI for generating and editing creative assets with AI providers. It supports OpenAI image generation and editing today, with a provider registry designed for audio, video, and broader model marketplaces over time.
+
+It is built for both developers and AI agents: predictable commands, parseable output, local auth profiles, YAML manifests, parallel execution, and a companion skill.
+
+## Supported Today
+
+| Area | Status |
+| --- | --- |
+| OpenAI auth profiles | Supported |
+| OpenAI image generation | Supported |
+| OpenAI image editing | Supported |
+| Context images and masks | Supported |
+| YAML/JSON batch manifests | Supported |
+| Dependency-aware parallel runs | Supported |
+| Agent instructions via `ploof learn` | Supported |
+| Additional providers | Planned |
+| Audio/video generation | Planned |
+
+## Install
+
+```bash
+bun i -g @miketromba/ploof
+```
+
+Other package managers:
+
+```bash
+npm install -g @miketromba/ploof
+pnpm add -g @miketromba/ploof
+yarn global add @miketromba/ploof
+```
+
+Run without installing:
+
+```bash
+bunx @miketromba/ploof --help
+npx @miketromba/ploof --help
+```
+
+## Quick Start
+
+```bash
+# Authenticate
+ploof login openai --api-key <your-api-key>
+
+# Generate an image
+ploof image generate \
+  --prompt "Studio product photo of a matte black water bottle" \
+  --out assets/hero.png \
+  --model gpt-image-1 \
+  --size 1024x1024
+
+# Edit an image with context
+ploof image edit \
+  --image assets/input.png \
+  --mask assets/mask.png \
+  --prompt "Replace the background with a clean marble countertop" \
+  --out assets/edited.png
+
+# Run a manifest
+ploof run assets.yaml --parallel 4
+```
+
+## Authentication
+
+Credentials are stored locally in `~/.ploof/credentials.json`.
+
+```bash
+ploof login openai --api-key <your-api-key>
+ploof login openai --api-key <your-api-key> --profile work
+ploof whoami openai
+ploof profiles openai
+ploof logout openai --profile work
+```
+
+If `--api-key` is omitted, `ploof login openai` reads
+`PLOOF_OPENAI_API_KEY` or `OPENAI_API_KEY`; in an interactive terminal it will
+prompt for a key without echoing it.
+
+Environment variables override stored credentials:
+
+```bash
+export PLOOF_OPENAI_API_KEY=sk-...
+# or
+export OPENAI_API_KEY=sk-...
+```
+
+OpenAI profile metadata:
+
+```bash
+ploof login openai \
+  --api-key <key> \
+  --organization <org-id> \
+  --project <project-id> \
+  --base-url <url>
+```
+
+## Image Generation
+
+```bash
+ploof image generate \
+  --provider openai \
+  --profile default \
+  --prompt "Editorial portrait, dramatic side light" \
+  --out assets/portrait.png \
+  --model gpt-image-1 \
+  --size 1024x1024 \
+  --quality high \
+  --format png
+```
+
+Useful flags:
+
+| Flag | Description |
+| --- | --- |
+| `--model <model>` | Provider model |
+| `--size <size>` | Image size |
+| `--quality <quality>` | Image quality |
+| `--format <format>` | Output image format |
+| `--n <count>` | Number of images |
+| `--background <value>` | Background setting |
+| `--moderation <value>` | Moderation setting |
+| `--response-format <format>` | Provider response format |
+| `--stream` | Request streaming image events |
+| `--param key=value` | Provider-specific pass-through parameter |
+| `--json '{...}'` | Provider-specific JSON object |
+
+## Image Editing
+
+```bash
+ploof image edit \
+  --provider openai \
+  --image input.png \
+  --image reference.png \
+  --mask mask.png \
+  --prompt "Keep the product, replace the background" \
+  --out edited.png
+```
+
+Use repeated `--image` flags for context/reference images. Use `--mask` when the selected provider/model supports masked edits.
+
+## Batch Manifests
+
+```yaml
+version: 1
+parallel: 4
+tasks:
+  - id: base
+    kind: image.generate
+    provider: openai
+    prompt: "Studio product photo"
+    params:
+      model: gpt-image-1
+      size: 1024x1024
+      quality: high
+    output: assets/base.png
+
+  - id: edit
+    kind: image.edit
+    provider: openai
+    needs: [base]
+    inputs:
+      images:
+        - task: base
+      mask: ./mask.png
+    prompt: "Add a premium background"
+    output: assets/final.png
+```
+
+Run it:
+
+```bash
+ploof run assets.yaml --parallel 4
+ploof run assets.yaml --dry-run --output json
+```
+
+## Output Formats
+
+Ploof defaults to table output in TTYs and compact output when piped.
+
+```bash
+ploof image generate --prompt "..." --output json
+ploof run assets.yaml --output jsonl
+ploof run assets.yaml --fields id,kind,outputs
+```
+
+Formats:
+
+| Format | Use case |
+| --- | --- |
+| `table` | Human-readable terminal output |
+| `compact` | Agent-friendly compact text |
+| `json` | Programmatic consumption |
+| `jsonl` | Streaming/pipeline consumption |
+
+## AI Agent Usage
+
+`ploof learn` is the canonical AI-agent reference for the installed CLI version:
+
+```bash
+ploof learn
+```
+
+Install the bootstrap skill:
+
+```bash
+ploof skill install
+```
+
+The skill is intentionally small and points agents to `ploof learn`, so operational instructions stay aligned with the installed npm package.
+
+## Configuration
+
+```bash
+ploof config list
+ploof config get output
+ploof config set output compact
+ploof config reset
+```
+
+Config is stored at `~/.ploof/config.json`.
+
+## Development
+
+```bash
+bun install
+bun run dev -- --help
+bun test
+bun run typecheck
+bun run lint
+bun run build
+```
+
+## Testing
+
+Run the full offline gate:
+
+```bash
+bun run lint
+bun run typecheck
+bun run test
+bun run build
+npm pack --dry-run
+```
+
+The default test suite includes mocked OpenAI end-to-end tests. Those tests run real `ploof` CLI commands against a local mock OpenAI server and verify generated files, edit uploads, sidecar metadata, and dependency-aware manifests without spending API credits.
+
+Live OpenAI tests are opt-in only:
+
+```bash
+PLOOF_OPENAI_API_KEY=sk-... bun test tests/e2e
+```
+
+Optional live-test overrides:
+
+```bash
+PLOOF_OPENAI_LIVE_MODEL=gpt-image-1
+PLOOF_OPENAI_LIVE_SIZE=1024x1024
+```
+
+## License
+
+MIT

package/SPEC.md

@@ -0,0 +1,426 @@
+# Ploof CLI Specification
+
+## Summary
+
+Ploof is an npm-published CLI for generating and editing assets through AI generation providers. It starts with OpenAI image generation and editing, but the architecture must support multiple authenticated providers, multiple asset modalities, provider-specific settings, and parallel execution across mixed jobs.
+
+The product should feel like a small, sharp developer tool: easy to run manually, predictable in scripts, and optimized for AI agents.
+
+## Naming
+
+- NPM package: `@miketromba/ploof`
+- CLI binary: `ploof`
+- Brand/site target: `ploof.sh`
+- Config directory: `~/.ploof`
+- Environment prefix: `PLOOF_`
+- Canonical agent reference command: `ploof learn`
+- Bootstrap skill: `skills/asset-generation/SKILL.md`
+
+Example:
+
+```bash
+bun i -g @miketromba/ploof
+ploof login openai --api-key "$OPENAI_API_KEY"
+ploof image generate --prompt "Studio product photo" --out assets/hero.png
+ploof learn
+```
+
+The unscoped npm name `ploof` was rejected by npm's similarity policy during
+publish because it is too close to `plop`. The canonical install package is
+therefore scoped, while the command remains the short `ploof` binary.
+
+## Prior Art And Conventions
+
+Ploof should follow the style and publishing conventions from existing CLI projects:
+
+- `loops-cli`
+- `polar-cli`
+- `lemonsqueezy-cli`
+- `issy`
+
+Conventions to preserve:
+
+- Bun-first TypeScript development.
+- `type: "module"`.
+- `commander` for CLI parsing.
+- `chalk` for terminal output where useful.
+- Biome for lint/format.
+- `bun test`, `bunx tsc --noEmit`, `bun run build`.
+- `bin/ploof.ts` development entrypoint.
+- `scripts/build.ts` bundles to `dist/ploof.js`.
+- Published package runs on Node 18+ and does not require Bun.
+- Published files are constrained to runtime artifacts, README, LICENSE, spec, and skill files.
+- GitHub Actions CI runs typecheck, tests, and build.
+- GitHub Actions publish runs on `v*` tags and supports npm trusted publishing/OIDC.
+- Human-readable output in TTY, compact output when piped, JSON/JSONL for agents and scripts.
+
+## Core Goals
+
+1. Authenticate with multiple asset generation providers.
+2. Allow multiple profiles per provider.
+3. Generate and edit assets with provider-specific settings.
+4. Accept input assets as context for provider APIs that support them.
+5. Run multiple generation jobs in parallel.
+6. Support dependency-aware batch manifests.
+7. Preserve provider-specific settings without requiring constant CLI redesign.
+8. Provide first-class AI agent support through `ploof learn` and an installable skill.
+9. Publish cleanly to npm with the short `ploof` binary.
+
+## Initial Provider Scope
+
+Version 1 starts with OpenAI only.
+
+Initial capabilities:
+
+- `image.generate`
+- `image.edit`
+
+Future providers should be added through the provider registry without changing the manifest model.
+
+Future high-leverage provider candidates:
+
+- fal.ai: strong multi-model generative media coverage.
+- Replicate: broad community model marketplace.
+- Hugging Face Inference Providers: centralized access to many hosted models/providers.
+
+## Auth And Profiles
+
+Credentials are stored in a local CLI-specific directory, matching prior CLI conventions:
+
+```text
+~/.ploof/config.json
+~/.ploof/credentials.json
+```
+
+Credential file shape:
+
+```json
+{
+  "providers": {
+    "openai": {
+      "profiles": {
+        "default": {
+          "apiKey": "sk-..."
+        }
+      },
+      "defaultProfile": "default"
+    }
+  }
+}
+```
+
+Environment overrides:
+
+- `PLOOF_OPENAI_API_KEY`
+- `OPENAI_API_KEY`
+
+The Ploof-specific env var wins over the provider-native env var. Stored credentials are used only when no env override is present.
+
+OpenAI profile metadata may also include:
+
+- `organization`
+- `project`
+- `baseURL`
+
+## CLI Commands
+
+### Global Flags
+
+```bash
+-o, --output <format>   table|compact|json|jsonl
+-f, --fields <list>     Comma-separated field selection
+-d, --detail            Include full details
+--no-color              Disable color
+--verbose               Debug output to stderr
+-q, --quiet             Data only, minimal extra text
+-y, --yes               Skip confirmation prompts
+```
+
+### Auth
+
+```bash
+ploof login openai --api-key <key> [--profile default] [--organization org] [--project proj] [--base-url url]
+ploof whoami [provider] [--profile default]
+ploof profiles [provider]
+ploof logout openai [--profile default]
+```
+
+`login`, `whoami`, `profiles`, and `logout` are the only authentication
+commands. Ploof should not expose a second equivalent auth namespace.
+
+`ploof login openai` accepts `--api-key`, reads `PLOOF_OPENAI_API_KEY` or
+`OPENAI_API_KEY` when the flag is omitted, and prompts without echoing input
+when run in an interactive terminal. Non-interactive login fails if no key is
+provided.
+
+### Config
+
+```bash
+ploof config list
+ploof config get output
+ploof config set output compact
+ploof config reset
+```
+
+### Image Generation
+
+```bash
+ploof image generate \
+  --provider openai \
+  --profile default \
+  --prompt "Studio product photo" \
+  --out assets/hero.png \
+  --model gpt-image-1 \
+  --size 1024x1024 \
+  --quality high \
+  --format png
+```
+
+The command should expose common OpenAI image parameters as first-class flags and allow pass-through parameters:
+
+```bash
+--param key=value
+--json '{"providerSpecific": true}'
+```
+
+### Image Editing
+
+```bash
+ploof image edit \
+  --provider openai \
+  --image input.png \
+  --image reference.png \
+  --mask mask.png \
+  --prompt "Replace the background" \
+  --out assets/edited.png
+```
+
+The CLI must support multiple context images where the provider supports them.
+
+### Batch Run
+
+```bash
+ploof run assets.yaml --parallel 4
+```
+
+Manifest example:
+
+```yaml
+version: 1
+parallel: 4
+tasks:
+  - id: base
+    kind: image.generate
+    provider: openai
+    prompt: "Studio product photo"
+    params:
+      model: gpt-image-1
+      size: 1024x1024
+      quality: high
+    output: assets/base.png
+
+  - id: edit
+    kind: image.edit
+    provider: openai
+    needs: [base]
+    inputs:
+      images:
+        - task: base
+      mask: ./mask.png
+    prompt: "Add a premium background"
+    output: assets/final.png
+```
+
+## Asset Input Model
+
+All input/context assets are normalized before provider execution:
+
+```ts
+type AssetInput = {
+  role: 'image' | 'mask' | 'reference' | 'style' | 'audio' | 'video'
+  source: string
+  mime?: string
+  name?: string
+}
+```
+
+Supported sources:
+
+- Local paths.
+- HTTP(S) URLs where the provider accepts URLs or where Ploof can download/read them.
+- `-` for stdin where applicable.
+- Previous task outputs in manifests.
+
+OpenAI image editing maps:
+
+- `role=image` to image input files.
+- `role=mask` to mask file.
+
+Future providers can map roles such as `reference`, `style`, `init-image`, `audio`, or `video` differently.
+
+## Provider Architecture
+
+Provider modules implement a common interface:
+
+```ts
+type Provider = {
+  id: string
+  capabilities: ProviderCapability[]
+  runImageGenerate(job, context): Promise<ProviderResult>
+  runImageEdit(job, context): Promise<ProviderResult>
+}
+```
+
+The provider registry owns:
+
+- Provider lookup.
+- Capability checks.
+- Credential resolution.
+- Provider-specific validation.
+
+The CLI should avoid hardcoding all provider behavior into command handlers.
+
+## Settings Strategy
+
+Ploof should support provider settings in three layers:
+
+1. Stable first-class flags for common options.
+2. Repeatable `--param key=value` flags.
+3. Full JSON override/merge through `--json`.
+
+This avoids a dead-end where every provider schema update requires a CLI redesign.
+
+## Output Strategy
+
+Default behavior:
+
+- TTY: `table`
+- Piped/non-TTY: `compact`
+
+Supported formats:
+
+- `table`
+- `compact`
+- `json`
+- `jsonl`
+
+Asset-producing commands should write the asset to disk and print structured metadata:
+
+```json
+{
+  "id": "hero",
+  "kind": "image.generate",
+  "provider": "openai",
+  "outputs": ["assets/hero.png"],
+  "metadata": {
+    "model": "gpt-image-1"
+  }
+}
+```
+
+Each generated file should have an optional sidecar metadata file:
+
+```text
+assets/hero.png
+assets/hero.png.json
+```
+
+The sidecar should include:
+
+- Provider.
+- Operation kind.
+- Prompt.
+- Params.
+- Output path.
+- Request metadata where available.
+- Timestamp.
+
+## Parallel Execution
+
+The batch runner should:
+
+- Respect `parallel` from the manifest or CLI override.
+- Run independent tasks concurrently.
+- Respect `needs` dependencies.
+- Fail fast by default.
+- Optionally continue on errors later.
+- Resolve previous task outputs into dependent task inputs.
+
+## Agent Support
+
+Ploof must have first-class agent support.
+
+The canonical agent reference lives in the installed CLI:
+
+```bash
+ploof learn
+```
+
+The bootstrap skill should be intentionally small:
+
+```text
+skills/asset-generation/SKILL.md
+```
+
+The skill should:
+
+- Trigger when agents need to generate, edit, or batch-create assets.
+- Tell the agent to run `ploof learn`.
+- Treat `ploof learn` as the source of truth for the installed version.
+- Avoid duplicating operational docs.
+
+The CLI should also include:
+
+```bash
+ploof skill install
+```
+
+This command should either install the local bootstrap skill where feasible or print the exact install instruction for supported skill managers.
+
+## Test Strategy
+
+Unit tests:
+
+- Config read/write/reset.
+- Auth profile storage and env precedence.
+- Output format resolution.
+- Param parsing.
+- Manifest parsing and dependency validation.
+- Provider registry lookup.
+- `ploof learn` stability.
+
+Integration-style tests:
+
+- CLI help exits successfully.
+- Auth login/status/logout lifecycle with temp home.
+- Manifest dry-run/planning behavior.
+
+Live OpenAI tests should be opt-in only:
+
+```bash
+PLOOF_OPENAI_API_KEY=... bun test tests/e2e
+```
+
+## Non-Goals For Initial Implementation
+
+- No browser UI.
+- No cloud service.
+- No keychain dependency.
+- No non-OpenAI provider implementation yet.
+- No hard promise that every future provider setting is a first-class flag.
+- No live API tests in default CI.
+
+## Initial Milestone Definition
+
+The initial complete implementation should include:
+
+- npm package scaffolding for `@miketromba/ploof`.
+- Build, test, typecheck, lint setup.
+- OpenAI auth profiles.
+- OpenAI image generate/edit.
+- Asset input normalization.
+- Manifest run with dependency-aware parallelism.
+- Output formats and sidecar metadata.
+- `ploof learn`.
+- Bootstrap skill.
+- README, LICENSE, GitHub Actions.