Run the CLI from Slack over Socket Mode, behind an admission gate

[Shashankss1205]

A Slack front door for the grapharc CLI, hostable on a laptop: python -m grapharc.slack holds one outbound Socket Mode WebSocket, so there is no public URL, no open port, no reverse proxy. /grapharc metrics t.jsonl r1 (or an @mention) from any Slack client runs the command on the host and posts the piped-mode bytes back in a code fence — the CLI's stable form, not a third output dialect.

The gate

Anyone in the workspace can talk to the bot, so what text may become an argv is an admission decision, in the repo's own idiom:

• Subcommands are allowlisted: demo run plan models replay diff trace metrics viz. agent (arbitrary tool execution on the host) and serve are not in the list.
• Flags are allowlisted per subcommand; --registry (imports an arbitrary module), --config, --json, --no-color are unreachable from Slack.
• Every path — positional or flag value, either --flag value or --flag=value form — must resolve inside the bot's working directory, refused before any process spawns.
• --model/--reviewer-model are refused unless the operator sets GRAPHARC_SLACK_ALLOW_MODEL=1 in the shell that starts the bot. Default spend from Slack: zero — every reachable command runs the scripted path.
• Argv only, never a shell string; timeout (default 120s) kills a runaway command and says so.

Modularity

command.py   the gate: Slack text -> argv, or a refusal that says why   (stdlib)
runner.py    sys.executable -m grapharc.cli.main, cwd = the confined dir (stdlib)
format.py    exit-code semantics (0/1/2) -> one Slack message, announced truncation, fence-escape defused (stdlib)
bot.py       the only file that touches slack-bolt, imported lazily
config.py    env only — deliberately NOT the .env upward search (issue #20)
__main__.py  python -m grapharc.slack; exit 2 + stderr when the env is not runnable

A module entry rather than a grapharc slack subcommand, because the parser help is printed verbatim in README.md and byte-compared by the suite; a daemon also doesn't belong in a parser whose every other command terminates.

Packaging and docs

• New slack extra (slack-bolt>=1.20), joined to [all] so the CI wheel-check imports the module with the dependency present; every module except bot.py imports without it.
• docs/cookbook/07-slack.md: Slack app manifest (scopes commands, app_mentions:read, chat:write), token setup, run instructions, the allow/refuse table, and the honest caveats (bot dies with the laptop lid; the workspace is the trust boundary).
• README extras list gains one line.

Testing

tests/test_slack_gateway.py — 21 tests, no token, no network: the gate's allow/deny/confinement decisions, an end-to-end run of the real CLI through the runner+formatter (success, exit-2, and the timeout kill), announced truncation, fence-escape defusal, config validation, and the missing-extra install hint (import failure faked, not skipped).

Full suite green locally, ruff check . clean.

🤖 Generated with Claude Code