@miranda0808/maya-codex 0.1.0 → 0.1.1

package/README.md

@@ -1,30 +1,39 @@
-# @miranda0808/maya-codex
-
-Install a full repo-local Maya runtime into the current project or a target directory.
-
-## Usage
-
-```bash
-npx @miranda0808/maya-codex init
-npx @miranda0808/maya-codex init --dry-run
-npx @miranda0808/maya-codex init --force
-npx @miranda0808/maya-codex init --target ../some-project
-```
-
-## What It Installs
-
-- portable `AGENTS.md`
-- `commands/`
-- `.maya/`
-- `templates/`
-- `campaigns/README.md`
-- `research/README.md`
-- `tools/`
-- `.agent/skills/`
-
-## Options
-
-- `--dry-run` prints the planned writes without modifying the target project.
-- `--force` overwrites files Maya previously installed.
-- `--target <path>` installs into a different existing directory.
-
+# @miranda0808/maya-codex
+
+Install a full repo-local Maya runtime into the current project or a target directory.
+
+## Usage
+
+```bash
+npx @miranda0808/maya-codex init
+npx @miranda0808/maya-codex init --dry-run
+npx @miranda0808/maya-codex init --force
+npx @miranda0808/maya-codex init --target ../some-project
+```
+
+## What It Installs
+
+- portable `AGENTS.md`
+- `.env.example`
+- `.gitignore` entries for `.env` and `.env.local`
+- `commands/`
+- `.maya/`
+- `templates/`
+- `campaigns/README.md`
+- `research/README.md`
+- `tools/`
+- `.agent/skills/`
+
+## Secrets
+
+After install, copy `.env.example` to `.env` or `.env.local` in the target repo.
+
+- `.env.local` overrides `.env` when both exist.
+- Maya keeps `.env` and `.env.local` out of git by adding them to `.gitignore`.
+- The Meta boundary auto-loads `META_ACCESS_TOKEN` and `META_AD_ACCOUNT_ID` from those files for each invocation.
+
+## Options
+
+- `--dry-run` prints the planned writes without modifying the target project.
+- `--force` overwrites files Maya previously installed.
+- `--target <path>` installs into a different existing directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miranda0808/maya-codex",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "bin": {
     "maya-codex": "bin/maya-codex.js"
   },

package/payload/.env.example

@@ -0,0 +1,9 @@
+# Copy this file to `.env` or `.env.local` in the Maya workspace.
+# `.env.local` overrides `.env` when both exist.
+# Local environment only. Do not commit real secrets.
+META_ACCESS_TOKEN=
+META_AD_ACCOUNT_ID=
+
+# Add other imported tool credentials only when you start using them.
+# RESEND_API_KEY=
+# GA4_ACCESS_TOKEN=

package/payload/tools/meta/README.md

@@ -1,55 +1,58 @@
-# Meta Tool Maintenance
-
-## Source
-
-- Vendored from the upstream `marketingskills` repository: [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)
-- Local CLI file: `tools/clis/meta-ads.js`
-- Approved Maya boundary: `tools/meta/meta-fetch.ps1`
-- Current local API base in the vendored file: `https://graph.facebook.com/v18.0`
-
-## Usage Boundary
-
-- Agents should prefer `tools/meta/meta-fetch.ps1` for Meta reads.
-- `meta-fetch.ps1` is the Maya-owned boundary for validation, read-only allowlisting, output sanitization, and cache writes.
-- Keep secrets in environment variables only.
-- Do not place raw tokens, headers, or unsafe debug output in prompts, logs, state files, or cache files.
-
-## Maintenance Policy
-
-- Treat `tools/clis/meta-ads.js` as vendored upstream code.
-- Do not hand-maintain feature changes in the vendored file unless there is an urgent local fix.
-- When the tool stops working, Meta deprecates an API version, or we need a newer endpoint or field, check the exact upstream tool first.
-- Prefer replacing the local vendored file from upstream over accumulating local drift.
-
-## Update Triggers
-
-Review the upstream `meta-ads.js` when any of the following happens:
-
-- Meta returns version deprecation or unsupported endpoint errors.
-- Expected fields disappear or response shapes change.
-- We need a newer Graph API version than the one pinned in the vendored file.
-- The upstream `marketingskills` repo updates the same tool.
-
-## Safe Update Workflow
-
-1. Compare the local `tools/clis/meta-ads.js` with the upstream `meta-ads.js` in `coreyhaines31/marketingskills`.
-2. Prefer a clean vendor refresh instead of manually mixing old and new logic.
-3. Re-run dry-run and read-only verification commands after updating.
-4. Keep any future Maya-specific safety behavior in wrappers under `tools/meta/`, not inside the vendored CLI unless strictly necessary.
-
-## Verification After A Bump
-
-Run at minimum:
-
-```powershell
-node --check 'tools/clis/meta-ads.js'
-powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.ps1' -Resource campaigns -Action list -DryRun
-powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.ps1' -Resource campaigns -Action insights -Id 123 -DatePreset last_30d -DryRun
-```
-
-Confirm:
-
-- syntax still passes
-- dry-run masks authorization data
-- command structure still matches expected usage
-- no local secrets are written to files, prompts, logs, or outputs
+# Meta Tool Maintenance
+
+## Source
+
+- Vendored from the upstream `marketingskills` repository: [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)
+- Local CLI file: `tools/clis/meta-ads.js`
+- Approved Maya boundary: `tools/meta/meta-fetch.ps1`
+- Current local API base in the vendored file: `https://graph.facebook.com/v18.0`
+
+## Usage Boundary
+
+- Agents should prefer `tools/meta/meta-fetch.ps1` for Meta reads.
+- `meta-fetch.ps1` is the Maya-owned boundary for validation, read-only allowlisting, output sanitization, env-file resolution, and cache writes.
+- Keep real secrets in repo-local `.env` or `.env.local`, or in already-loaded environment variables.
+- `meta-fetch.ps1` resolves `.env` first, then `.env.local`, while preserving explicitly set process env values.
+- Do not place raw tokens, headers, or unsafe debug output in prompts, logs, state files, or cache files.
+
+## Maintenance Policy
+
+- Treat `tools/clis/meta-ads.js` as vendored upstream code.
+- Do not hand-maintain feature changes in the vendored file unless there is an urgent local fix.
+- When the tool stops working, Meta deprecates an API version, or we need a newer endpoint or field, check the exact upstream tool first.
+- Prefer replacing the local vendored file from upstream over accumulating local drift.
+
+## Update Triggers
+
+Review the upstream `meta-ads.js` when any of the following happens:
+
+- Meta returns version deprecation or unsupported endpoint errors.
+- Expected fields disappear or response shapes change.
+- We need a newer Graph API version than the one pinned in the vendored file.
+- The upstream `marketingskills` repo updates the same tool.
+
+## Safe Update Workflow
+
+1. Compare the local `tools/clis/meta-ads.js` with the upstream `meta-ads.js` in `coreyhaines31/marketingskills`.
+2. Prefer a clean vendor refresh instead of manually mixing old and new logic.
+3. Re-run dry-run and read-only verification commands after updating.
+4. Keep any future Maya-specific safety behavior in wrappers under `tools/meta/`, not inside the vendored CLI unless strictly necessary.
+
+## Verification After A Bump
+
+Run at minimum:
+
+```powershell
+node --check 'tools/clis/meta-ads.js'
+powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.test.ps1'
+powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.ps1' -Resource campaigns -Action list -DryRun
+powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.ps1' -Resource campaigns -Action insights -Id 123 -DatePreset last_30d -DryRun
+```
+
+Confirm:
+
+- syntax still passes
+- dry-run masks authorization data
+- `.env` and `.env.local` resolution works without leaking tokens
+- command structure still matches expected usage
+- no local secrets are written to files, prompts, logs, or outputs