platphormctl

platphormctl is the PlatPhormNews command-line control plane. It discovers the network from https://platphormnews.com/api/network/graph, validates public-safe platform surfaces, exercises MCP JSON-RPC, runs integration harnesses, emits trace context, and writes local reports without faking results.

Binary aliases:

• platphormctl
• phormctl
• pctl

Install

pnpm install
pnpm build
node dist/cli.js --help
pnpm npx:smoke

The package targets Node.js 22+ and writes local state under .platphormctl/ unless PLATPHORMCTL_HOME is set. After publication, it is intended to run through npx @platphormnews/platphormctl or the binary aliases platphormctl, phormctl, and pctl.

Quick Start

platphormctl network discover --json
platphormctl simple start
platphormctl network status --best-effort
platphormctl network validate --best-effort --evidence --json
platphormctl site inspect docs --json
platphormctl site discovery mcp --json
platphormctl chain image-phorm-opencontent ./image.jpeg --dry-run --json
platphormctl mcp validate mcp --json
platphormctl mcp examples mcp --json --output .platphormctl/artifacts/mcp-examples.json
platphormctl trace headers --json
platphormctl harness run discovery-full --json --best-effort

Live Exercise Scripts

Repository scripts run controlled public-safe evidence passes outside the normal test runner:

pnpm exercise:opencontent -- --url https://platphormnews.com --best-effort
pnpm exercise:working-sites -- --concurrency 4 --max-tools-per-site 10 --best-effort

exercise:opencontent probes https://opencontent.platphormnews.com/api/docs, /api/v1/*, discovery files, and /api/mcp, then previews and submits the provided URLs through real API and MCP paths. exercise:working-sites discovers hosts from the root network graph, checks standard routes, parses public OpenAPI GET operations, initializes MCP where available, and calls public-safe non-mutating tools with generated payloads.

Both scripts write results.json, summary.md, and per-site evidence under .platphormctl/artifacts/live-exercise/. They propagate trace headers, redact secrets and x-vercel-ja4-digest, and report 404/degraded/auth-required states instead of faking success.

Protected Examples

Protected commands require PLATPHORM_API_KEY through the environment or --api-key env:NAME.

PLATPHORM_API_KEY=... platphormctl mcp call docs publish_report --protected --input '{}'
platphormctl docs submit --file report.md --protected --yes --api-key env:PLATPHORM_API_KEY
platphormctl publish file report.md --to docs --protected --yes --api-key env:PLATPHORM_API_KEY
platphormctl publish remove <document-id-or-slug> --from docs --protected --yes --api-key env:PLATPHORM_API_KEY

Raw secrets are redacted from logs, reports, output, and trace metadata.

Command Matrix

Core groups: network, site, simple, service, mcp, trace, harness, llm, report, doctor.

service list, service help <site>, and service call <site> <action> are generated from the verified route source truth plus live OpenAPI/MCP capability discovery. Static service aliases such as ascii, browserops, opencontent, and sandbox remain executable for compatibility, but root help hides the generated alias list so operators use the dynamic source of truth first.

Future *.platphormnews.com services are discovered from the network graph and can be inspected with site or service commands without code changes.

chain image-phorm-opencontent is the first tool-to-tool operator chain. It converts a local image through the ASCII API/MCP, saves ascii.txt and ascii.png, auto-detects red/green/blue circles in JPEG sources, creates a Phorm design payload with triangle overlays, and publishes the resulting Markdown/image/design artifact to OpenContent when --protected, PLATPHORM_API_KEY, and --yes are supplied.

network route-map is the agent-operable route discovery pipeline. It discovers canonical routes from live evidence, classifies hardcoded/missing/degraded route families, writes per-site evidence, saves verified route truth to source-of-truth.json, emits next-commands.ndjson, and generates repair-ready degraded-feature documents:

platphormctl network route-map --json --trace --evidence --best-effort --out .platphormctl/artifacts/route-map/smoke
platphormctl docs degraded generate --from-route-map .platphormctl/artifacts/route-map/smoke/route-map.json --json --trace
platphormctl docs degraded publish --from-route-map .platphormctl/artifacts/route-map/smoke/route-map.json --to docs --dry-run --json --trace

Protected degraded-doc publication requires PLATPHORM_API_KEY, --protected, and --yes.

Agent-first catalog commands expose machine-readable command/workflow/capability surfaces for autonomous execution planning:

platphormctl catalog agent commands --json
platphormctl catalog agent workflows --json
platphormctl catalog agent capabilities --service opencontent --live --json
platphormctl catalog agent plan opencontent --live --json

No-Mock Policy

Production commands call real public-safe routes or return degraded, auth_required, or unavailable with remediation. Mocks are only used in tests and fixtures.

CI

pnpm lint
pnpm typecheck
pnpm test
pnpm test:live
pnpm test:full-network
pnpm test:protected-live
pnpm test:mutating-live
pnpm exercise:opencontent -- --url https://platphormnews.com --best-effort
pnpm exercise:working-sites -- --limit 25 --best-effort
pnpm build
node dist/cli.js doctor secrets --json

See docs/ for configuration, harness, MCP, security, trace, LLM, and examples.

pnpm test:full-network is intentionally strict: it fails when any discovered standard route returns 404 and writes evidence under .platphormctl/artifacts/live-e2e/ plus network validate evidence under .platphormctl/artifacts/network-validate/.