cli-meta-ads 0.1.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "cli-meta-ads",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Agent-ready CLI for Meta Ads with safe read, draft and approval-gated write flows.",
+  "keywords": [
+    "meta",
+    "facebook",
+    "instagram",
+    "ads",
+    "marketing-api",
+    "cli",
+    "agent-ready"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Brixon-Group/CLI-meta-ads.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Brixon-Group/CLI-meta-ads/issues"
+  },
+  "homepage": "https://github.com/Brixon-Group/CLI-meta-ads#readme",
+  "bin": {
+    "meta": "dist/index.js",
+    "meta-ads": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs/TECHNICAL.md",
+    "AI_CONTEXT.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "REQUIREMENTS.md",
+    "examples",
+    "skills/meta-cli-operator"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/index.js",
+    "clean": "rm -rf dist coverage .vitest",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.1",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.43.0",
+    "@typescript-eslint/parser": "^8.43.0",
+    "eslint": "^9.35.0",
+    "globals": "^16.4.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/skills/meta-cli-operator/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: meta-cli-operator
+description: Operate, verify, troubleshoot, and extend the `CLI-meta-ads` repository safely. Use when an agent needs to run the Meta Ads CLI, inspect or validate command behavior, debug auth/config/provider issues, update command surfaces, add new commands, adjust approval or safety logic, or document how the CLI should be used.
+---
+
+# Meta CLI Operator
+
+## Overview
+
+Use this skill to work inside the `CLI-meta-ads` repo without rediscovering its operating model. Prefer safe verification first, preserve the draft/approval semantics for writes, and keep code, tests, and docs in sync when the CLI changes.
+
+## Quick Start
+
+1. Read [../../README.md](../../README.md) for setup, runtime expectations, and operator-facing behavior.
+2. Read [../../docs/TECHNICAL.md](../../docs/TECHNICAL.md) for architecture and update boundaries.
+3. Read [../../AI_CONTEXT.md](../../AI_CONTEXT.md) for the compact repo summary.
+4. Read [../../AGENTS.md](../../AGENTS.md) before changing CLI behavior, because it lists which files must be updated together.
+5. Build context from the actual command entrypoints in [../../src/cli/build-cli.ts](../../src/cli/build-cli.ts) and the relevant command/domain/client modules before editing.
+6. Reuse the bundled example specs in [../../examples/README.md](../../examples/README.md) when you need a valid starting point for create or launch flows.
+
+## Safe Operating Workflow
+
+### 1. Verify before assuming
+
+- Run `npm run lint`, `npm run typecheck`, and `npm run test` before and after substantive code changes.
+- Use `node dist/index.js --help` after build-level changes.
+- Run `npm pack --dry-run` before release-oriented changes so the published tarball stays clean.
+- Prefer `meta auth login`, `meta auth status`, `meta doctor`, and `meta verify-api` for live verification paths.
+
+### 2. Keep reads and writes distinct
+
+- Read commands are safe by default.
+- Mutation commands must stay draft-first.
+- Do not silently convert a draft-only or approval-only flow into a direct write.
+- Preserve the `--apply` gate and the approval webhook semantics.
+- Keep approval webhooks on `https://...` only.
+- Keep `--debug` output sanitized; never print access tokens or raw secret-bearing URLs.
+- Keep config resolution explicit; do not rely on hidden host-local env files outside the documented env/config sources.
+
+### 3. Change the smallest coherent layer
+
+- Command shape changes: start in [../../src/cli/build-cli.ts](../../src/cli/build-cli.ts) and the relevant file in `src/commands/`.
+- Validation changes: update `src/validators/`.
+- Provider behavior changes: update `src/domain/meta-ads-service.ts` and, if needed, `src/client/meta-api-client.ts`.
+- Safety/approval changes: update `src/domain/approval-service.ts` and the affected command handlers.
+- Output or exit-code changes: update `src/output/render.ts` and `src/utils/errors.ts`.
+
+## Common Tasks
+
+### Run the CLI safely
+
+1. Ensure env/config is present as described in [../../README.md](../../README.md).
+2. Prefer read commands first:
+   - `node dist/index.js auth login`
+   - `node dist/index.js auth status`
+   - `node dist/index.js whoami`
+   - `node dist/index.js doctor --account <id>`
+   - `node dist/index.js verify-api --account <id>`
+3. For human operators, prefer the Facebook Login for Business user-token flow over shared system-user tokens.
+4. Use `META_ACCESS_TOKEN` directly only when you intentionally want non-interactive automation or server-side execution.
+5. For automation or machine inspection, add `--json`.
+6. For single-account commands, pass a concrete ad account id; reserve `all` for explicit multi-account reads such as `performance` or `anomalies`.
+7. For mutations, inspect draft output first and only then consider `--apply`.
+8. For create flows, prefer JSON spec files and keep MVP object creation on `PAUSED` unless the repo explicitly broadens that contract.
+   - start from the validated examples in `examples/single-object/` or `examples/launch/` instead of inventing ad hoc shapes
+9. When touching create specs, preserve the current provider-safe defaults and pre-validation rules:
+   - non-CBO campaigns still need explicit ad-set budget sharing state
+   - ad sets default `bidStrategy` from `bidAmount`
+   - Advantage+ Audience ages are normalized before provider calls
+   - direct creative creation and launch both support `formats.feed4x5|square1x1|story9x16`; the legacy `platformCustomizations.instagram` path still exists for backward compatibility
+10. For orchestrated create flows, prefer `launch validate` and `launch plan` before `launch apply`, and keep the generated receipt for `launch resume`.
+11. When preparing a release, verify that `examples/` and `skills/meta-cli-operator/` still ship in the npm artifact and that no repo-local files leak into it.
+
+### Add or modify a command
+
+1. Update the command tree in [../../src/cli/build-cli.ts](../../src/cli/build-cli.ts) if the top-level registration changes.
+2. Update or add the command module in `src/commands/`.
+3. Update validation, domain logic, and provider calls in the appropriate lower layers.
+4. Add or update tests in `tests/unit/`.
+5. Update docs listed in [../../AGENTS.md](../../AGENTS.md).
+
+### Troubleshoot provider or auth issues
+
+1. Check config resolution in `src/config/file-config.ts`.
+2. Check auth guards in `src/auth/guards.ts`.
+3. Check the browser-login bootstrap in `src/auth/login.ts` for `config_id`, redirect URI, and callback parsing behavior.
+4. Check HTTP error mapping and retries in `src/client/meta-api-client.ts`.
+5. Check account discovery fallbacks in `src/client/meta-discovery.ts`.
+6. Re-run `doctor` and `verify-api`.
+
+## Update Discipline
+
+When behavior changes, update these docs unless the change is provably internal-only:
+
+- [../../README.md](../../README.md)
+- [../../docs/TECHNICAL.md](../../docs/TECHNICAL.md)
+- [../../AI_CONTEXT.md](../../AI_CONTEXT.md)
+- [../../AGENTS.md](../../AGENTS.md)
+- [../../CLAUDE.md](../../CLAUDE.md)
+
+If the change affects agent usage patterns, also update [references/update-matrix.md](./references/update-matrix.md).
+
+## References
+
+- Read [references/update-matrix.md](./references/update-matrix.md) when changing commands, config, provider behavior, docs, or tests.

package/skills/meta-cli-operator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Meta CLI Operator"
+  short_description: "Operate the Meta Ads CLI safely."
+  default_prompt: "Use $meta-cli-operator to inspect, verify, and operate the Meta Ads CLI safely."

package/skills/meta-cli-operator/references/update-matrix.md

@@ -0,0 +1,117 @@
+# Update Matrix
+
+Use this file when changing the CLI so code, tests, and docs stay aligned.
+
+## Core file map
+
+- `src/index.ts`: process entrypoint
+- `src/cli/build-cli.ts`: top-level command registration
+- `src/cli/context.ts`: config resolution and shared runtime context
+- `src/cli/action.ts`: action wrapper, result rendering, exit code flow
+- `src/commands/*.ts`: command handlers
+- `src/commands/assets.ts`: asset upload flows
+- `src/commands/adsets.ts`: ad set creation flows
+- `src/commands/creatives.ts`: creative creation flows
+- `src/commands/launch.ts`: launch orchestration commands
+- `src/domain/meta-ads-service.ts`: provider-facing operations and normalization
+- `src/domain/launch-service.ts`: launch receipts, sequencing, resumable execution
+- `src/domain/approval-service.ts`: approval policy and webhook submission
+- `src/domain/analytics.ts`: local reporting/anomaly/fatigue logic
+- `src/client/meta-api-client.ts`: HTTP, retries, pagination, error mapping
+- `src/client/meta-discovery.ts`: managed account discovery
+- `src/config/file-config.ts`: env/config precedence and local config persistence
+- `src/auth/login.ts`: Facebook Login for Business bootstrap, callback parsing, auth-code exchange
+- `src/auth/guards.ts`: token and permission guards
+- `src/output/render.ts`: text and JSON rendering
+- `src/utils/errors.ts`: exit codes and error taxonomy
+- `src/utils/security.ts`: secret redaction and HTTPS-only webhook normalization
+- `src/validators/common.ts`: CLI-boundary validation
+- `src/validators/create-spec.ts`: JSON create-spec validation
+- `src/validators/launch-spec.ts`: JSON launch-spec validation and ref integrity
+- `tests/unit/*.test.ts`: unit and command behavior coverage
+
+## If you change X, update Y
+
+### New command or renamed command
+
+- Update `src/cli/build-cli.ts`
+- Update or add the relevant `src/commands/*.ts`
+- Add tests in `tests/unit/`
+- Update `README.md`
+- Update `docs/TECHNICAL.md`
+- Update `AI_CONTEXT.md`
+- Update `AGENTS.md`
+- Update `CLAUDE.md`
+
+### New flags, args, or validation rules
+
+- Update the relevant command file
+- Update `src/validators/common.ts` if validation is shared
+- Add or update tests
+- Update `README.md`
+- Update `docs/TECHNICAL.md` if the contract or flow changed
+- Update `AI_CONTEXT.md` if agent usage patterns changed
+
+### Provider endpoint, payload, retry, pagination, or error handling
+
+- Update `src/domain/meta-ads-service.ts`
+- Update `src/client/meta-api-client.ts`
+- Update `src/client/meta-discovery.ts` if account discovery is affected
+- Update tests
+- Update `docs/TECHNICAL.md`
+- Update `README.md` if operator-visible behavior changed
+- Re-check official Meta links in the docs if source URLs changed
+- Preserve secret redaction in debug/error surfaces and fail loudly on pagination safety caps.
+
+### Approval or safety behavior
+
+- Update `src/domain/approval-service.ts`
+- Update affected command files
+- Update tests
+- Update `README.md`
+- Update `docs/TECHNICAL.md`
+- Update `AI_CONTEXT.md`
+- Update `AGENTS.md`
+- Update `CLAUDE.md`
+- Preserve HTTPS-only webhook validation and minimized approval argv payloads.
+
+### Config, env vars, default paths, or precedence
+
+- Update `src/config/file-config.ts`
+- Update `src/auth/login.ts` if browser-login bootstrap, redirect handling, or auth-code exchange changed
+- Update `src/cli/context.ts` if runtime context changed
+- Update tests
+- Update `README.md`
+- Update `docs/TECHNICAL.md`
+- Update `AI_CONTEXT.md`
+- Update `AGENTS.md`
+- Update `CLAUDE.md`
+
+### Output shape or exit codes
+
+- Update `src/output/render.ts` and/or `src/utils/errors.ts`
+- Update tests
+- Update `README.md`
+- Update `docs/TECHNICAL.md`
+- Update `AI_CONTEXT.md` if automation-facing behavior changed
+
+### Auth command or login flow changes
+
+- Update `src/commands/auth.ts`
+- Update `src/auth/login.ts`
+- Update auth-related tests
+- Update `README.md`
+- Update `docs/TECHNICAL.md`
+- Update `AI_CONTEXT.md`
+- Update `CLAUDE.md`
+
+## Verification checklist after changes
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+npm pack --dry-run
+node dist/index.js --help
+```