Skip to content
Back to search

ax

SkillWorks with CodexGitHub

the agent experience layer · observability + memory for AI coding agents (Claude Code + Codex) · local-first, typed, yours

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Necmttn/ax with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Necmttn/ax'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/necmttn--ax/badge.svg)](/listings/necmttn--ax)

HTML

<a href="/listings/necmttn--ax"><img src="/api/listings/necmttn--ax/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 7 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "ax",
  3. "description": "ax - the agent experience layer. Local graph of every Claude Code + Codex session, skill invocation, edit, and commit. Surfaces what to use, what to ground on, and which experiments to package next.",
  4. "version": "0.1.1",
  5. "homepage": "https://github.com/Necmttn/ax",
  6. "author": "Necmttn"
  7. }
README.md · README · 354 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ax
  2. ###### the retro loop for AI coding agents
  3. **Make your agent learn.**
  4. Turn every agent session into a better next run.
  5. [Website](https://ax.necmttn.com) · [Documentation](https://ax.necmttn.com/docs)
  6. ---
  7. Every sub-agent you spawn finishes its work and disappears. Whatever it
  8. figured out - which command failed three times before the right one, which
  9. file actually mattered, which approach to skip - dies with it. The next
  10. sub-agent rediscovers it from scratch. Your own next session does too.
  11. `ax` watches every session your harness runs, spots the mistakes it
  12. repeats, and turns them into small, repo-specific fixes you review and
  13. apply - one at a time.
  14. Under the hood, the `/retro` workflow pulls unreviewed sessions from the local
  15. graph when you ask for them. It records a structured retro (*tried · worked ·
  16. failed · next*) and turns repeated friction into proposals you review. Accepted
  17. proposals become experiments with verdicts after 3, 10, and 30 sessions. The
  18. next session reads what worked.
  19. > *What did this sub-agent learn? Which experiments are still open?
  20. > Which skills earned their keep? What did that branch cost in tokens?*
  21. > `ax` answers these by reading what already happened.
  22. ![ax · the retro loop for AI coding agents](docs/images/og.png)
  23. ## 60 seconds in
  24. ```bash
  25. curl -fsSL ax.necmttn.com/install | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 36 on GitHub
  26. PATH="$HOME/.local/bin:$PATH" ax setup # agent skills + first ingest + doctor
  27. ```
  28. Or skip the terminal entirely - paste this into Claude Code / Codex and your
  29. agent installs ax, ingests your history, labels your skills, and tells you
  30. which ones to actually use:
  31. <details>
  32. <summary><strong>the setup prompt - give this to your agent</strong></summary>
  33. <!-- MANUAL MIRROR of AGENT_ONBOARDING_WITH_INSTALL in packages/onboarding-prompt/src/index.ts
  34. (README can't import TS). If you change the prompt, regenerate this block:
  35. bun -e "import('./packages/onboarding-prompt/src/index.ts').then(m=>process.stdout.write(m.AGENT_ONBOARDING_WITH_INSTALL))"
  36. Use the relative path, not the `@ax/onboarding-prompt` specifier - the
  37. latter does not resolve from a git worktree. Drift is now a test failure:
  38. packages/onboarding-prompt/src/readme-mirror.test.ts -->
  39. ```text
  40. Set up ax for me, end to end. ax is a local agent-experience graph over my Claude Code + Codex history - it runs locally and I review every change.
  41. PRIVACY (read first, so you can answer if I ask whether this is safe to run): ax is fully local - no daemon, no server to install or connect to. Ingest reads my transcripts, git history, and tool calls into a local DuckDB cache file on my machine - nothing is uploaded, there is no account, no cloud, and no outbound call at ingest. The only commands that can leave my machine are explicit opt-in, consent-gated surfaces: `ax profile publish` shares an aggregates-only JSON (counts, day streaks, model split, skill/hook names, taste-pattern summaries) to a public gist I control - NEVER transcript content, code, project names, or file paths; `ax profile widget` commits a marker-delimited block to my public GitHub profile README; `ax contribute pattern` opens a GitHub PR containing one reviewed taste-pattern JSON file. `--no-cost` strips the publish dollar figures too, and `ax profile unpublish` deletes the gist. Do NOT run `ax profile publish` or `ax profile widget` or `ax contribute pattern` as part of this setup. If I ask about privacy or data handling, answer from these facts; it's AGPL-3.0, so you can also read the source to confirm.
  42. A note from Neco (ax's founder): ax is early and I'm hungry for feedback - every bug, wrong number, or rough edge you send back makes it sharper for everyone. Please don't hold back; if something's off, help me fix it.
  43. CONTRIBUTE-BACK (do this whenever a trigger below fires; never publish anything without showing it to me first and getting an explicit yes): Triggers - a step fails; a fact you report looks wrong or surprising to me; you spot a clear bug or improvement in ax itself. When one fires: ask me 2-3 sharp questions to pin down what I expected, which command/hook/agent is involved, and how often - enough for a repro. Then draft a GitHub issue for github.com/Necmttn/ax, show me the full draft, and on my yes file it via `gh` (the ax-repo skill). If a session is the evidence, run `ax share --dry-run` first, show me the redacted gist, and only publish with `ax share` on my yes - then link it in the issue.
  44. 1. INSTALL - run `curl -fsSL ax.necmttn.com/install | bash` to install the ax CLI. Reference: https://ax.necmttn.com/docs
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 63 on GitHub
  45. 2. INGEST MY HISTORY - first run `ax ingest --dry-run` and tell me, in plain words, how long a full backfill will take. Then start the ingest in the BACKGROUND so we can keep working: run `ax ingest` as a background job with AX_PROGRESS=plain, and watch its output for progress and completion. Tell me I can watch it fill live in the dashboard - run `ax studio` and open http://127.0.0.1:1738. If it fails or lands zero data after finishing, that's a CONTRIBUTE-BACK trigger. When the ingest finishes, summarize what landed: total sessions, turns, and the top skills/tools I actually use.
  46. 3. VERIFY - run `ax doctor`. If anything isn't ok, diagnose and fix it, then re-run until it is. If the cause is a bug in ax itself (not my environment), that's a CONTRIBUTE-BACK trigger.
  47. 4. REALITY CHECK - show me the headline facts (sessions, turns, top skills + tools), then ask: does this match how I actually work? Heads-up: verification often hides inside PR commands, hooks, and subagents, so if a number reads lower than my gut says, that's a likely miss. If I disagree with any fact, that's a CONTRIBUTE-BACK trigger - my disagreement is the repro.
  48. 5. LABEL what ax can't classify - run `ax skills classify`. It writes one `.ax/tasks/classify-<skill>.md` brief per skill I use but ax can't role-tag. For each brief: read the skill, decide its role(s), and fill the YAML frontmatter at the top (`primary_role:` is required; `secondary`, `confidence`, `rationale` are optional). Run `ax roles` to see labels already in use. Then run `ax skills lint` to apply them. If it says "no unclassified skills", that's fine. Then show `ax skills weighted` and `ax skills config`; tell me which skills you labeled and why, and flag anything ax marked orphan or out-of-scope.
  49. 6. BUILD MY PROFILE + AGENT WRAPPED - first run `ax profile show` for a quick text fingerprint (sessions, active days + streak, model split, top skills, installed hooks, workflow arcs, taste patterns) and read it back to me in a few sentences. THEN build my Agent Wrapped deck, because the dashboard's Wrapped tab stays BLANK until you do - ingest does not fill it. Run `ax wrapped generate`; it writes a brief to `.ax/tasks/wrapped-generate-<date>.md`. Follow that brief: mine my graph for the answers and assemble the recap cards as `{ "cards": [{question, headline, body, sensitivity?}] }` JSON, then publish them with `ax wrapped publish --file=<your-cards.json>` (or pipe the JSON on stdin). Now my Wrapped deck is populated - tell me to run `ax studio` and open http://127.0.0.1:1738 to see it. All of this stays LOCAL: `ax profile show` and `ax wrapped publish` write only to my own machine and upload nothing. Do NOT run `ax profile publish` or `ax profile widget` or `ax contribute pattern` as part of this setup.
  50. 7. GATHER MY INSIGHTS IN PARALLEL - the three areas below are independent and only READ the local graph, so fan them out instead of running them one by one: dispatch one subagent per area, all at once (cap ~3 concurrent - they read the same local cache). Give each subagent your MOST CAPABLE / strongest-reasoning model - do NOT route these down to a cheap model. This is a one-time setup and the commands can error or return surprising output, so I want an agent that can actually diagnose, retry, and interpret what it sees, not just paste noise back. Brief each one clearly: its area, the exact commands to run, and what to return - the raw output plus a tight read of what stands out (the biggest number, anomalies, anything that looks broken). The areas: (a) SPEND - `ax cost sessions`, `ax cost routability`, `ax dispatches --candidates`; (b) FRICTION - `ax improve recommend`, `ax insights friction`, `ax insights tools`; (c) HISTORY (run inside one of my git repos) - `ax sessions here --days=30`, `ax recall "<a topic worth searching>"`. When all three return, synthesize across them for me: my single biggest cost driver and the largest concrete saving, the top 1-2 fixes worth accepting and why (if I say yes, run `ax improve accept <id>` then `ax improve lint`), and one genuinely useful thing from my history.
  51. 8. GIVE ME A NEXT STEP - recommend 1-2 under-used skills you'd reach for based on what you saw, then end with a concrete CTA: the exact command or prompt I should run next, and what outcome it will produce.
  52. ```
  53. </details>
  54. Then ask the graph things you couldn't ask before:
  55. ```bash
  56. ax recall "auth bug" # full-text recall across every past session
  57. ax skills taste # which skills earned their keep
  58. ax costs for --branch main # what a branch cost in tokens
  59. ax sessions metrics # graph-derived session health
  60. ax share <session-id> # publish a session anyone can read
  61. ax studio # live dashboard at http://127.0.0.1:1738
  62. ```
  63. Requires Bun ≥ 1.3. **No database server** - the graph is an embedded DuckDB
  64. file plus a small SQLite sidecar for the decisions you make, so there is
  65. nothing to install, start, or connect to. macOS-first; Linux works for ingest
  66. and CLI (the one optional launchd agent is the telemetry receiver). Dev
  67. install, schema, queries, benchmarks:
  68. [`docs/development.md`](docs/development.md).
  69. ## Every harness, one graph
  70. Six harnesses - Claude Code, Codex, Pi, Omp, OpenCode, and Cursor - plus installed
  71. skills, local git history, and GitHub PRs with their reviews and checks, all
  72. ingested into one local graph: sessions, turns, tool calls, plans, skills,
  73. commits, files, friction, compaction, derived signals. Ingest is a staged
  74. Effect pipeline; unchanged sources are skipped, so re-ingest takes seconds.
  75. Reading keeps it current - a query against a stale graph quietly forks a
  76. catch-up ingest in the background, so nothing has to be running while you are
  77. not using ax. Everything is a file on your own disk - no network round-trip,
  78. no third party, no server.
  79. Signals are normalized across harnesses: "context ran out and got summarized"
  80. is one queryable compaction event whether it came from Claude Code or Codex.
  81. The pipeline in one line: **every event → typed graph → ranked interventions**.
  82. ```mermaid
  83. flowchart LR
  84. cc["~/.claude/projects/<br/>Claude transcripts"]
  85. cx["~/.codex/sessions/<br/>Codex transcripts"]
  86. pi["~/.pi/agent/sessions/<br/>Pi transcripts"]
  87. omp["~/.omp/agent/sessions/<br/>oh-my-pi (omp) transcripts"]
  88. oc["OpenCode + Cursor<br/>SQLite stores"]
  89. sk["installed skills<br/>(.claude, .agents, plugins)"]
  90. g[("local git history")]
  91. gh["GitHub PRs<br/>reviews + checks"]
  92. cc --> ingest
  93. cx --> ingest
  94. pi --> ingest
  95. omp --> ingest
  96. oc --> ingest
  97. sk --> ingest
  98. g --> ingest
  99. gh --> ingest
  100. ingest["axctl ingest<br/>(Effect pipelines)"] --> db
  101. db[("the ax graph<br/>session · turn · tool_call · skill · plan<br/>repository · checkout · commit · file<br/>friction · diagnostic · compaction · insight")]
  102. db --> cli["axctl CLI<br/>recall · skills · insights · evidence"]
  103. db --> dash["axctl studio<br/>on-demand dashboard"]
  104. db --> agent["agent skill + ax mcp<br/>project context · verify · harness"]
  105. ```
  106. ## Recall every session you ever ran
  107. Full-text BM25 search across turns, commits, and skills - milliseconds, local:
  108. ```text
  109. $ ax recall "auth middleware"
  110. 4 matches
  111. 2026-05-23T15:19 codex user acme-app alright lets commit auth related work for now
  112. 2026-05-23T14:51 codex assistant acme-app Added the HealthOS just setup. You can now run from repo root: just health dev …
  113. 2026-05-23T14:41 codex assistant acme-app Findings: apple-auth.service.ts accepts extra Apple audiences from ambient env …
  114. 2026-05-19T11:08 claude user ax the auth middleware retry loop - we still see exit-code 1 from bun check after …
  115. ```
  116. ## Know which skills earned their keep
  117. Composite score over the last 30 days, across every installed skill:
  118. ```text
  119. $ ax skills taste --limit=8
  120. skill scope score 7d 30d total
  121. codex:exec_command codex-tool 40902.5 1,124 30,500 40,389
  122. codex:write_stdin codex-tool 6,957 166 4,932 6,451
  123. codex:rescue command 781 0 389 605
  124. codex:update_plan codex-tool 766.5 14 338 391
  125. simplify user 718.5 5 89 101
  126. codex:wait_agent codex-tool 713 3 497 507
  127. codex:spawn_agent codex-tool 647 2 439 442
  128. superpowers:systematic-debugging plugin 26.5 0 6 6
  129. (8 / 288 skills shown)
  130. ```
  131. And which tools fail most often, so you know what to skill-up around:
  132. ```text
  133. $ ax insights tools --limit=5
  134. name failure_count exit_code last_seen
  135. write_stdin 647 1 2026-05-23T14:34
  136. Edit 483 - 2026-05-23T05:14
  137. Skill 475 - 2026-05-05T13:34
  138. exec_command 421 1 2026-05-22T18:50
  139. Bash 318 1 2026-05-21T22:12
  140. ```
  141. 31 read-only graph views in `ax insights`; full list in
  142. [`docs/insights-cli-reference.md`](docs/insights-cli-reference.md).
  143. ## Put a price on everything
  144. Token cost resolved through model pricing rows - prompt, output, cache
  145. read/write, estimated USD - queryable by session, text, commit, or branch:
  146. ```bash
  147. ax costs summary --since=7 # by provider/model, last 7 days
  148. ax costs for --query "live-traces" # cost of sessions matching turn text
  149. ax costs for --commit 464c80b # cost of the sessions behind a commit
  150. ax costs for --branch feat/share # cost of a whole feature branch
  151. ```
  152. So "what did that refactor cost" has an answer with a dollar sign on it.
  153. ## Route the expensive model where it earns its keep
  154. Your frontier model burns 3-10x cheaper-model rates on mechanical subagent
  155. work unless you route it. ax measures the leak, nudges at dispatch time, and
  156. proves whether the routing worked:
  157. ```bash
  158. ax cost split --days=7 # main loop vs subagents, by model
  159. ax dispatches --candidates # model-less dispatches + est savings
  160. ax routing tune # mine YOUR history for new routing classes
  161. ax routing compile # regenerate the table (user classes preserved)
  162. ax hooks install ~/.ax/hooks/route-dispatch.ts --providers=claude
  163. ```
  164. The `route-dispatch` hook warns when a mechanical dispatch forgets an explicit
  165. model; the `efficient-dispatch` skill (via `npx skills add Necmttn/ax`) teaches
  166. the orchestration pattern; `ax improve recommend` surfaces a proposal when
  167. missed savings accumulate; `ax routing tune` mines new routing classes from
  168. your own dispatch history (judgment work is never auto-routed - vet those via
  169. `--emit-brief`). One source of truth - `~/.ax/hooks/routing-table.json` -
  170. measured end to end. See [docs/design/cost-routing.md](docs/design/cost-routing.md).
  171. ## Share a session like a gist
  172. ```bash
  173. ax share <session-id>
  174. # → https://ax.necmttn.com/s/<owner>/<gist-id>
  175. ```
  176. Exports the full session - subagent transcripts, harness hook fires, per-turn
  177. pricing - sanitizes it, publishes it as a GitHub Gist, and serves it through a
  178. hosted viewer: unified tool-call cards, session timeline, cost rail, and a
  179. per-session poster image for the link unfurl. The data stays in your gist,
  180. under your account; the viewer just renders it.
  181. ## Watch your agents work
  182. `ax studio` opens the dashboard over your published snapshot. It is ephemeral
  183. by design: it binds a port only while a browser is attached and exits on its
  184. own afterward, so there is no daemon to start, find, or stop - and nothing left
  185. running when you close the tab:
  186. - **Transcript view** - tool call and result as one card, skill and image
  187. turns folded, subagent spawns with their metrics.
  188. - **Session timeline** - highlights, segments, and events derived from the
  189. graph, no LLM in the loop.
  190. - **Session canvas** - a semantic-zoom lineage graph of sessions and the
  191. subagents they spawned: swimlanes, time-axis zoom up to 2000x, hover detail
  192. in ~30ms.
  193. - **Live ingest** - trigger a run from the dashboard and watch stages stream;
  194. refresh mid-run and it resumes where it was.
  195. - **Metrics** - `ax sessions metrics` and `ax signals` surface graph-derived
  196. session health (fragility cascades, plan churn, tool retries), and
  197. `ax sessions compare` puts two runs side by side.
  198. - **Harness doctor** - grades how well your setup is actually working;
  199. every fix you apply moves the score.
  200. ## Close the loop: grounded agent files
  201. ![tried · worked · failed · next - the retro loop](docs/images/retro-loop.png)
  202. ax recommends changes to your `AGENTS.md` / `CLAUDE.md` / skills - grounded in
  203. evidence from your own sessions - and tracks which lines came from it:
  204. ```text
  205. session ends ax retro emit # structured note: tried · worked · failed · next
  206. proposals derive ax improve recommend # ranked by confidence × recency × frequency
  207. pick one ax improve accept <id> # writes .ax/tasks/<id>.md - hand to your agent
  208. reconcile ax improve lint # marker ↔ DB ↔ task files
  209. verdict at +3/+10/+30 ax improve verdict --set=adopted|ignored|regressed|partial
  210. sessions # session-count windows, not calendar days
  211. ```
  212. Every proposal carries its evidence trail (`ax improve show <id>`). Verdicts
  213. land on session-count windows, so a skill that stopped firing gets caught, not
  214. forgotten.
  215. ## Author your own guards
  216. Write a hook once in typed TypeScript, prove it against your own history, run it in Claude Code and Codex.
  217. ```bash
  218. ax hooks init # scaffold ~/.ax/hooks (TypeScript, @ax/hooks-sdk)
  219. ax hooks backtest ~/.ax/hooks/my-guard.ts # replay weeks of real tool calls through it first
  220. ax hooks install ~/.ax/hooks/my-guard.ts --providers=claude,codex
  221. ax hooks latency [--days=7] [--baseline=21] # regression lens: recent vs baseline p95 per hook event
  222. ```
  223. ## Your agent can query all of this mid-session
  224. Two integration paths, same graph:
  225. ```bash
  226. npx skills add Necmttn/ax # agent skills: setup, retro, extract-workflow, dojo, …
  227. claude mcp add ax -- ax mcp # MCP server: read-only graph queries as tools
  228. ```
  229. Recommended agent loop: `ax project context --json` before work (stack, recent
  230. friction, verification commands), do the work, `ax project verify --json`
  231. before reporting done. For Codex, add `ax mcp` to `~/.codex/config.toml`. Tool
  232. list and details: [`docs/cli.md`](docs/cli.md#mcp-server-tools).
  233. ## Why an experience layer
  234. LLM agents are good at tasks. They're bad at remembering what happened.
  235. Memory tooling today is either a giant rolling context window (expensive,
  236. slow, lossy) or vague vector retrieval (no structure, no grounding in real
  237. events).
  238. `ax` takes a different shape: a **typed graph of evidence** built from the
  239. agent's own logs. Three things fall out of that, and they're the three things
  240. "agent experience" actually means in practice:
  241. 1. **Skill triage** - which of your installed skills get used, which never
  242. fire, which correlate with stuck sessions.
  243. 2. **Pre-flight grounding** - `ax project context` hands the next agent
  244. stack info, recent friction, and verification commands.
  245. 3. **Retro signal** - query the graph after a hard session: tool retries,
  246. plan churn, file edit pairings. Feed it back into the next run.
  247. `AX` (agent experience) is what the agent perceives across sessions, reflects
  248. on at the end of each, and turns into the next experiment. It is to AI coding
  249. agents what retros and post-mortems are to engineering teams - a structured
  250. reflection step that compounds. A longer take:
  251. [`docs/manifesto.md`](docs/manifesto.md).
  252. ## Docs
  253. - [`docs/cli.md`](docs/cli.md) - full CLI reference, costs, improve, MCP tools
  254. - [`docs/manifesto.md`](docs/manifesto.md) - the missing layer in the agent stack
  255. - [`docs/language.md`](docs/language.md) - coined vocabulary, the AX glossary
  256. - [`docs/brand.md`](docs/brand.md) - design system + voice rules
  257. - [`docs/development.md`](docs/development.md) - local setup, schema, queries, benchmarks
  258. - [`CONTRIBUTING.md`](CONTRIBUTING.md) - PR conventions, ground rules
  259. - [`CONTEXT.md`](CONTEXT.md) - domain glossary (Repository vs. Checkout vs. …)
  260. - [`docs/adr/`](docs/adr/) - architecture decisions
  261. ## Community
  262. Questions, feedback, or want to shape where ax goes next? Join the Discord:
  263. [discord.gg/E4R88Cvr5R](https://discord.gg/E4R88Cvr5R)
  264. ## License
  265. If it shapes your agent, you should be able to fork it.
  266. [AGPL-3.0-only](LICENSE) © 2025 Necmettin Karakaya. A
  267. [commercial license](docs/COMMERCIAL-LICENSE.md) is available for use that the
  268. AGPL doesn't permit - reach out via the Discord above.
apps/axctl/src/cli/install-otlpd-plist.test.ts · Bundled script · 185 lines · 1 finding marked
  1. import { describe, expect, it } from "bun:test";
  2. import { spawnSync } from "node:child_process";
  3. import {
  4. escapeXmlText,
  5. otlpdPlist,
  6. resolveOtlpdPlistDecision,
  7. resolveTelemetryConsent,
  8. telemetryConsentConflict,
  9. } from "./install.ts";
  10. /** Best-effort well-formedness check via whichever validator is on PATH. */
  11. function assertWellFormedXml(xml: string): void {
  12. const plutil = spawnSync("plutil", ["-lint", "-"], { input: xml, encoding: "utf8" });
  13. if (plutil.error === undefined && plutil.status !== null) {
  14. expect(plutil.status).toBe(0);
  15. return;
  16. }
  17. const xmllint = spawnSync("xmllint", ["--noout", "-"], { input: xml, encoding: "utf8" });
  18. if (xmllint.error === undefined && xmllint.status !== null) {
  19. expect(xmllint.status).toBe(0);
  20. }
  21. }
  22. describe("otlpd install wiring", () => {
  23. it("builds a standalone LaunchAgent for ax otlpd", () => {
  24. const plist = otlpdPlist("/Users/test/.local/bin/ax");
  25. expect(plist).toContain("<string>com.necmttn.ax-otlpd</string>");
  26. expect(plist).toMatch(/<key>RunAtLoad<\/key>\s*<true\/>/);
  27. expect(plist).toContain("otlpd.out");
  28. expect(plist).toContain("otlpd.err");
  29. });
  30. it("uses direct ProgramArguments - no shell, no bash -lc wrapper", () => {
  31. const plist = otlpdPlist("/Users/test/.local/bin/ax");
  32. expect(plist).not.toContain("/bin/bash");
  33. expect(plist).not.toContain("-lc");
  34. expect(plist).not.toContain("exec ");
  35. expect(plist).toMatch(
  36. /<key>ProgramArguments<\/key>\s*<array>\s*<string>\/Users\/test\/\.local\/bin\/ax<\/string>\s*<string>otlpd<\/string>\s*<\/array>/,
  37. );
  38. });
  39. it("keeps working for the source-checkout bin\\/axctl wrapper path", () => {
  40. const plist = otlpdPlist("/Users/test/repo/apps/axctl/bin/axctl");
  41. expect(plist).toMatch(
  42. /<key>ProgramArguments<\/key>\s*<array>\s*<string>\/Users\/test\/repo\/apps\/axctl\/bin\/axctl<\/string>\s*<string>otlpd<\/string>\s*<\/array>/,
  43. );
  44. assertWellFormedXml(plist);
  45. });
  46. it("keeps working for the compiled-binary execPath", () => {
  47. const plist = otlpdPlist("/Users/test/.local/bin/axctl");
  48. expect(plist).toMatch(
  49. /<key>ProgramArguments<\/key>\s*<array>\s*<string>\/Users\/test\/\.local\/bin\/axctl<\/string>\s*<string>otlpd<\/string>\s*<\/array>/,
  50. );
  51. assertWellFormedXml(plist);
  52. });
  53. it("escapes an ampersand in binPath so the plist stays well-formed", () => {
  54. const plist = otlpdPlist("/Users/a&b/bin/ax");
  55. expect(plist).toContain("<string>/Users/a&amp;b/bin/ax</string>");
  56. expect(plist).not.toContain("/Users/a&b/bin/ax");
  57. assertWellFormedXml(plist);
  58. });
  59. it("escapes a less-than sign in binPath so the plist stays well-formed", () => {
  60. const plist = otlpdPlist("/Users/a<b/bin/ax");
  61. expect(plist).toContain("<string>/Users/a&lt;b/bin/ax</string>");
  62. expect(plist).not.toContain("<b/bin/ax<");
  63. assertWellFormedXml(plist);
  64. });
  65. it("escapes quotes in binPath", () => {
  66. const plist = otlpdPlist(`/Users/a"b'c/bin/ax`);
  67. expect(plist).toContain("<string>/Users/a&quot;b&apos;c/bin/ax</string>");
  68. assertWellFormedXml(plist);
  69. });
  70. it("carries shell metacharacters through as inert literal text, never as a command", () => {
  71. const dangerous = "/Users/$(rm -rf /);`id`|bin/ax";
    • Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
    • Line 87 on GitHub
  72. const plist = otlpdPlist(dangerous);
  73. // No shell wrapper exists to interpret these - they must appear as
  74. // plain escaped XML text inside a single <string> element.
  75. expect(plist).toContain(escapeXmlText(dangerous));
  76. expect(plist).not.toContain("/bin/bash");
  77. assertWellFormedXml(plist);
  78. });
  79. it("escapes an optional AX_OTLP_SPOOL_DIR env value", () => {
  80. const prev = process.env.AX_OTLP_SPOOL_DIR;
  81. process.env.AX_OTLP_SPOOL_DIR = "/Users/spool&<dir>";
  82. try {
  83. const plist = otlpdPlist("/Users/test/.local/bin/ax");
  84. expect(plist).toContain("<key>AX_OTLP_SPOOL_DIR</key>");
  85. expect(plist).toContain("<string>/Users/spool&amp;&lt;dir&gt;</string>");
  86. assertWellFormedXml(plist);
  87. } finally {
  88. if (prev === undefined) delete process.env.AX_OTLP_SPOOL_DIR;
  89. else process.env.AX_OTLP_SPOOL_DIR = prev;
  90. }
  91. });
  92. it("omits AX_OTLP_SPOOL_DIR entirely when unset", () => {
  93. const prev = process.env.AX_OTLP_SPOOL_DIR;
  94. delete process.env.AX_OTLP_SPOOL_DIR;
  95. try {
  96. const plist = otlpdPlist("/Users/test/.local/bin/ax");
  97. expect(plist).not.toContain("AX_OTLP_SPOOL_DIR");
  98. } finally {
  99. if (prev === undefined) delete process.env.AX_OTLP_SPOOL_DIR;
  100. else process.env.AX_OTLP_SPOOL_DIR = prev;
  101. }
  102. });
  103. });
  104. describe("escapeXmlText", () => {
  105. it("escapes ampersand first so entities are not double-escaped", () => {
  106. expect(escapeXmlText("a & b")).toBe("a &amp; b");
  107. });
  108. it("escapes less-than and greater-than", () => {
  109. expect(escapeXmlText("<tag>")).toBe("&lt;tag&gt;");
  110. });
  111. it("escapes double and single quotes", () => {
  112. expect(escapeXmlText(`"quoted" 'single'`)).toBe("&quot;quoted&quot; &apos;single&apos;");
  113. });
  114. it("leaves plain text untouched", () => {
  115. expect(escapeXmlText("/Users/test/.local/bin/ax")).toBe("/Users/test/.local/bin/ax");
  116. });
  117. });
  118. describe("telemetryConsentConflict (pure flag validation)", () => {
  119. it("flags --telemetry and --no-telemetry together", () => {
  120. expect(telemetryConsentConflict(true, true)).toBe(
  121. "axctl install: --telemetry and --no-telemetry cannot be used together",
  122. );
  123. });
  124. it("no conflict for every other combination", () => {
  125. expect(telemetryConsentConflict(false, false)).toBeNull();
  126. expect(telemetryConsentConflict(true, false)).toBeNull();
  127. expect(telemetryConsentConflict(false, true)).toBeNull();
  128. });
  129. });
  130. describe("resolveTelemetryConsent (tri-state, #findings-1)", () => {
  131. it("--telemetry grants consent", () => {
  132. expect(resolveTelemetryConsent(true, false)).toBe("grant");
  133. });
  134. it("--no-telemetry revokes consent", () => {
  135. expect(resolveTelemetryConsent(false, true)).toBe("revoke");
  136. });
  137. it("no flag at all preserves whatever consent state already exists", () => {
  138. // This is the load-bearing case: a plain `ax install` re-run must
  139. // NOT read as "--no-telemetry" (that used to unload a previously
  140. // consented otlpd agent - see resolveOtlpdPlistDecision below).
  141. expect(resolveTelemetryConsent(false, false)).toBe("preserve");
  142. });
  143. });
  144. describe("resolveOtlpdPlistDecision (cmdInstall's otlpd plist state machine)", () => {
  145. // The old "ax serve owns the OTLP port" contention case is gone - ax
  146. // otlpd is the only LaunchAgent ax installs, so there is no serve
  147. // LaunchAgent left to contend with it. One case per consent value.
  148. it("default install (no flags) preserves prior consent - never touches the plist", () => {
  149. // Whether the plist was previously written+loaded (prior --telemetry
  150. // consent) or is absent, "preserve" always no-ops either way - the
  151. // decision does not even need to know which case it's in.
  152. expect(resolveOtlpdPlistDecision("preserve")).toEqual({ action: "noop" });
  153. });
  154. it("explicit --telemetry always writes and loads", () => {
  155. expect(resolveOtlpdPlistDecision("grant")).toEqual({ action: "write-and-load" });
  156. });
  157. it("explicit --no-telemetry always unloads", () => {
  158. expect(resolveOtlpdPlistDecision("revoke")).toEqual({ action: "unload" });
  159. });
  160. });

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.