@theholocron/holocron-plugin-axiom 5.0.0-alpha.44 → 5.0.0-alpha.441

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  Axiom plugin for [Holocron](../cli). Implements the `logs` capability
6
6
  against [Axiom's REST API](https://axiom.co/docs/restapi/introduction),
7
- plus exports `verifyToken` + `AUTH_HINT` for use by `holocron auth`.
7
+ plus exports `verifyToken` + `AUTH_HINT` for use by `holocron check token`.
8
8
 
9
9
  > This plugin does **not** ship log lines. `@theholocron/observability/logger`'s
10
10
  > Axiom transport reads `HOLOCRON_AXIOM_TOKEN` / `HOLOCRON_AXIOM_DATASET`
@@ -26,14 +26,14 @@ Token resolution order:
26
26
  2. `HOLOCRON_AXIOM_TOKEN` env var (preferred — explicit intent)
27
27
  3. `AXIOM_TOKEN` env var (Axiom-native, works in CI)
28
28
  4. Keyring `axiom.<org>` — tried first when an org is active via `--org`, `HOLOCRON_ORG`, or `org` in `holocron.config.ts`
29
- 5. Keyring `axiom` — unnamespaced fallback; set via `holocron auth set axiom <token>`
29
+ 5. Keyring `axiom` — unnamespaced fallback; set via `holocron new token axiom <token>`
30
30
  6. `AuthError` naming both env vars + the auth hint
31
31
 
32
32
  Generate an API token at **app.axiom.co/settings/api-tokens** with
33
33
  permission to read and create datasets.
34
34
 
35
35
  ```bash
36
- holocron auth set axiom.theholocron <TOKEN>
36
+ holocron new token axiom.theholocron <TOKEN>
37
37
  ```
38
38
 
39
39
  **CI**: the keyring is unavailable in headless containers — expose the
@@ -49,27 +49,28 @@ token as `HOLOCRON_AXIOM_TOKEN` (or `AXIOM_TOKEN`) in the workflow env.
49
49
  }
50
50
  ```
51
51
 
52
- No options are required. `holocron setup` provisions the `holocron-ci`
53
- and `holocron-local` datasets; `holocron doctor` checks the dataset
54
- named by `HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET`. An explicit
55
- `logs: ["axiom", { "dataset": "holocron-ci" }]` overrides the env var
56
- for `doctor`.
52
+ No options are required. `holocron setup` provisions the CLI's dataset (`holocron`)
53
+ named by `HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET`; every environment of the CLI ships to
54
+ it and is told apart by the `env` field on each line. `holocron doctor` checks
55
+ the same dataset. An explicit `logs: ["axiom", { "dataset": "my-dataset" }]`
56
+ overrides the env var for `doctor`.
57
57
 
58
- `HOLOCRON_AXIOM_DATASET` is **not a secret** — set it in your shell
59
- profile locally (`holocron-local`) or as an org CI secret
60
- (`holocron-ci`). Leave it unset locally to skip Axiom entirely.
58
+ The dataset name is **not a secret** — it is the org variable `HOLOCRON_AXIOM_DATASET`,
59
+ synced from 1Password. Leave the token unset locally to skip Axiom entirely.
61
60
 
62
61
  ## What's implemented
63
62
 
64
- | Method | Behavior |
65
- | --------------- | ------------------------------------------------------------------------------------------------ |
66
- | `describe` | Returns `{ provider: "axiom", envKeys: ["HOLOCRON_AXIOM_TOKEN", "HOLOCRON_AXIOM_DATASET"] }`. |
67
- | `whoami` | `GET /v2/datasets/{dataset}` — verifies the token and the configured dataset's reachability. |
68
- | `ensureDataset` | `GET /v2/datasets/{name}`; on 404, `POST /v2/datasets`. Returns `{ alreadyExists }`. Idempotent. |
63
+ | Method | Behavior |
64
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
65
+ | `describe` | Returns `{ provider: "axiom", envKeys: ["HOLOCRON_AXIOM_TOKEN", "HOLOCRON_AXIOM_DATASET"] }`. |
66
+ | `whoami` | `GET /v2/datasets/{dataset}` — verifies the token and the configured dataset's reachability. |
67
+ | `ensureDataset` | `GET /v2/datasets/{name}`; on 404, `POST /v2/datasets`. Returns `{ alreadyExists }`. Idempotent. |
68
+ | `readDataset` | `GET /v2/datasets/{name}`; a 404 is `{ exists: false }` and nothing is created. Returns `retentionDays` when Axiom does. |
69
+ | `checkToken` | `GET` of a dataset that cannot exist: a 404 means the token is accepted, a 401 means it is refused, anything else throws. |
69
70
 
70
71
  Plugin-level exports (not capability methods, per the auth-bootstrap convention):
71
72
 
72
- | Export | Purpose |
73
- | ------------- | ------------------------------------------------------------------------------------------- |
74
- | `verifyToken` | `GET /v2/user` — returns `{ ok: true, subject: "user @ …" }` or `{ ok: false, message }`. |
75
- | `AUTH_HINT` | One-line hint printed by `holocron auth set` when no token is supplied or the token is bad. |
73
+ | Export | Purpose |
74
+ | ------------- | -------------------------------------------------------------------------------------------- |
75
+ | `verifyToken` | `GET /v2/user` — returns `{ ok: true, subject: "user @ …" }` or `{ ok: false, message }`. |
76
+ | `AUTH_HINT` | One-line hint printed by `holocron new token` when no token is supplied or the token is bad. |
package/dist/index.d.mts CHANGED
@@ -1,39 +1,10 @@
1
- import { AuthError, Logs, ResolveTokenInput } from "@theholocron/cli";
2
- //#region src/auth.d.ts
3
- declare const resolveToken: (input?: ResolveTokenInput) => string;
4
- //#endregion
5
- //#region src/rest.d.ts
6
- /** Axiom dataset — the subset of fields Holocron reads. */
7
- interface AxiomDataset {
8
- id: string;
9
- name: string;
10
- description?: string;
11
- }
12
- /** Axiom user — the subset returned by `GET /v2/user`. */
13
- interface AxiomUser {
14
- id: string;
15
- name?: string;
16
- email?: string;
17
- emails?: string[];
18
- }
19
- interface AxiomClientOptions {
20
- token: string;
21
- /** Override the API base URL (default `https://api.axiom.co`). */
22
- baseUrl?: string;
23
- /** Override `fetch` for tests. */
24
- fetch?: typeof fetch;
25
- }
26
- interface AxiomRestClient {
27
- getDataset(name: string): Promise<AxiomDataset>;
28
- createDataset(input: {
29
- name: string;
30
- description?: string;
31
- }): Promise<AxiomDataset>;
32
- getCurrentUser(): Promise<AxiomUser>;
33
- }
34
- declare function createAxiomClient(opts: AxiomClientOptions): AxiomRestClient;
35
- //#endregion
36
- //#region src/capabilities/logs.d.ts
1
+ import { AuthError, Logs, LogsDataset, PluginToken, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
2
+ import { AxiomClient, AxiomClientOptions, AxiomDataset, AxiomUser, CreateAxiomDatasetInput, createAxiomClient } from "@theholocron/axiom-client";
3
+ /** Resolves the Axiom token from `--token`, `HOLOCRON_AXIOM_TOKEN`, `AXIOM_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
4
+ export declare const resolveToken: import("@theholocron/cli").TokenResolver;
5
+ /** Every token this plugin takes, for `holocron doctor secrets --verify`, with what each layer's token must and must not be able to do. */
6
+ export declare const tokens: PluginToken[];
7
+ /** Options for the Axiom `logs` capability. */
37
8
  interface AxiomLogsOptions {
38
9
  /**
39
10
  * Target dataset, resolved from `HOLOCRON_AXIOM_DATASET` /
@@ -42,16 +13,19 @@ interface AxiomLogsOptions {
42
13
  */
43
14
  dataset?: string;
44
15
  }
45
- declare class AxiomLogs implements Logs {
16
+ /** The `logs` capability for Axiom: checks a dataset is reachable and creates datasets that are missing. */
17
+ export declare class AxiomLogs implements Logs {
46
18
  private readonly client;
47
19
  private readonly opts;
20
+ /** The capability key, always `logs`. */
48
21
  readonly key: "logs";
22
+ /** The provider name, `axiom`. */
49
23
  readonly providerName = "axiom";
50
24
  /**
51
25
  * `client` is a thunk — the token is resolved on first call, so
52
26
  * `describe()` (which needs no auth) works without one.
53
27
  */
54
- constructor(client: () => AxiomRestClient, opts: AxiomLogsOptions);
28
+ constructor(client: () => AxiomClient, opts: AxiomLogsOptions);
55
29
  describe(): Promise<{
56
30
  provider: string;
57
31
  envKeys: string[];
@@ -60,43 +34,35 @@ declare class AxiomLogs implements Logs {
60
34
  ok: boolean;
61
35
  dataset: string;
62
36
  }>;
37
+ readDataset(name: string): Promise<LogsDataset>;
38
+ checkToken(): Promise<{
39
+ ok: boolean;
40
+ reason?: string;
41
+ }>;
63
42
  ensureDataset(name: string): Promise<{
64
43
  alreadyExists: boolean;
65
44
  }>;
66
45
  }
67
- //#endregion
68
- //#region src/verify-token.d.ts
69
- /**
70
- * `verifyToken` — plugin-level export used by `holocron auth set axiom`
71
- * + `holocron auth check`. Hits `GET /v2/user` and translates the
72
- * response into the normalized `VerifyTokenResult` shape.
73
- *
74
- * Kept as a standalone function (not a capability method) so the auth
75
- * command can call it without initializing the full plugin.
76
- */
77
- interface VerifyTokenSuccess {
78
- ok: true;
79
- subject: string;
80
- }
81
- interface VerifyTokenFailure {
82
- ok: false;
83
- message: string;
84
- }
85
- type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
86
46
  interface VerifyTokenOptions {
87
47
  baseUrl?: string;
88
48
  fetch?: typeof fetch;
89
49
  }
90
- declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
91
- //#endregion
92
- //#region src/index.d.ts
93
- interface AxiomPluginOptions extends ResolveTokenInput, AxiomLogsOptions {
50
+ /**
51
+ * Checks an Axiom token by fetching the current user; the success subject is `user @` followed by the email, name or id,
52
+ * the failure carries the error message. An API token cannot read the user (403), so then it asks for a dataset that
53
+ * does not exist: a 404 means the token is accepted and may read datasets, and the subject says `API token`.
54
+ */
55
+ export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
56
+ /** Options for the Axiom plugin: token resolution, the target dataset and test overrides. */
57
+ export interface AxiomPluginOptions extends ResolveTokenInput, AxiomLogsOptions {
94
58
  /** Override base URL for tests. */
95
59
  baseUrl?: string;
96
60
  /** Override `fetch` for tests. */
97
61
  fetch?: typeof fetch;
98
62
  }
99
- interface PluginContext {
63
+ /** What the plugin's capabilities share: the resolved options and a lazily built client. */
64
+ export interface PluginContext {
65
+ /** The options, with `dataset` resolved from config, `HOLOCRON_AXIOM_DATASET` or `AXIOM_DATASET` (in that order). */
100
66
  options: AxiomPluginOptions & {
101
67
  dataset?: string;
102
68
  };
@@ -106,20 +72,26 @@ interface PluginContext {
106
72
  * no auth (`describe`) works without a token, and the loader never
107
73
  * aborts on a plugin whose token happens to be absent.
108
74
  */
109
- client: () => AxiomRestClient;
75
+ client: () => AxiomClient;
110
76
  }
111
- declare function createContext(options: AxiomPluginOptions): PluginContext;
112
- declare function logs(ctx: PluginContext): Logs;
113
- declare function createPlugin(options: AxiomPluginOptions): {
77
+ /** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
78
+ export declare function createContext(options: AxiomPluginOptions): PluginContext;
79
+ /** Builds the `logs` capability from a plugin context. */
80
+ export declare function logs(ctx: PluginContext): Logs;
81
+ /** Creates the Axiom plugin: the `connection` and `token` probes and the `logs` capability. */
82
+ export declare function createPlugin(options: AxiomPluginOptions): {
114
83
  name: string;
84
+ probes: {
85
+ token: import("@theholocron/cli").Probe;
86
+ connection: import("@theholocron/cli").Probe;
87
+ };
115
88
  capabilities: {
116
89
  logs: () => Logs;
117
90
  };
118
91
  };
119
92
  /**
120
- * One-line hint shown by `holocron auth set axiom` when no token is
93
+ * One-line hint shown by `holocron new token axiom` when no token is
121
94
  * supplied or when the supplied token is rejected.
122
95
  */
123
- declare const AUTH_HINT: string;
124
- //#endregion
125
- export { AUTH_HINT, AuthError, type AxiomClientOptions, type AxiomDataset, AxiomLogs, type AxiomLogsOptions, AxiomPluginOptions, type AxiomRestClient, type AxiomUser, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createAxiomClient, createContext, createPlugin, logs, resolveToken, verifyToken };
96
+ export declare const AUTH_HINT: string;
97
+ export { AuthError, type AxiomClient, type AxiomClientOptions, type AxiomDataset, type AxiomLogsOptions, type AxiomUser, type CreateAxiomDatasetInput, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createAxiomClient };
package/dist/index.mjs CHANGED
@@ -1,17 +1,59 @@
1
- import { AuthError, ProviderApiError, createResolveToken, createRestClient } from "@theholocron/cli";
2
- //#region src/auth.ts
1
+ import { AuthError, ProviderApiError, connectionProbe, createResolveToken, tokenExpectations } from "@theholocron/cli";
2
+ import { createEnvLookup, firstEnv } from "@theholocron/env-utils/lookup";
3
+ import { errorMessage } from "@theholocron/misc-utils";
4
+ import { createAxiomClient } from "@theholocron/axiom-client";
5
+ // src/probes/token/expectations.ts
6
+ /**
7
+ * Datasets the logging setup retired (ADR-0019): one dataset per service now, split by the `env` field. A token that
8
+ * still reaches one is shown, so a layer pointed at the wrong dataset (`holocron-local` on a laptop) is visible.
9
+ */
10
+ const RETIRED_DATASETS = [
11
+ "holocron-local",
12
+ "holocron-ci",
13
+ "holocron-global"
14
+ ];
15
+ const RULES = {
16
+ read: "required",
17
+ ingest: "required",
18
+ query: "absent"
19
+ };
20
+ /**
21
+ * What each layer's Axiom token is meant to carry, the same as "What each Axiom token needs" in
22
+ * `docs/src/content/docs/tokens.mdx`. Every layer ships to the same dataset and only passes the environment as a field,
23
+ * so it is one token with the same permissions everywhere: it ingests (the logger) and reads the dataset (`doctor
24
+ * logs`), and does not query, because nothing in the repo reads logs back, so a leaked token cannot either. The probe
25
+ * still tries query, so a token that can is flagged. This is the plugin's `tokens` declaration, read through
26
+ * `tokenExpectations()`; change it and that table together.
27
+ */
28
+ const EXPECTED = { permissions: {
29
+ local: RULES,
30
+ dev: RULES,
31
+ ci: RULES,
32
+ prod: RULES
33
+ } };
34
+ // src/auth.ts
35
+ /** Resolves the Axiom token from `--token`, `HOLOCRON_AXIOM_TOKEN`, `AXIOM_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
3
36
  const resolveToken = createResolveToken({
4
37
  envName: "HOLOCRON_AXIOM_TOKEN",
5
38
  vendorEnvName: "AXIOM_TOKEN",
6
39
  keyringService: "axiom",
7
- errorMessage: "no Axiom token found. Pass --token <TOKEN>, set HOLOCRON_AXIOM_TOKEN / AXIOM_TOKEN, or run: holocron auth set axiom <TOKEN>"
40
+ errorMessage: "no Axiom token found. Pass --token <TOKEN>, set HOLOCRON_AXIOM_TOKEN / AXIOM_TOKEN, or run: holocron new token axiom <TOKEN>"
8
41
  });
9
- //#endregion
10
- //#region src/capabilities/logs.ts
42
+ /** Every token this plugin takes, for `holocron doctor secrets --verify`, with what each layer's token must and must not be able to do. */
43
+ const tokens = [{
44
+ ...resolveToken.token,
45
+ expect: EXPECTED
46
+ }];
47
+ // src/capabilities/logs.ts
48
+ /** A dataset that does not exist: asking for it tells a token Axiom accepts (404) from one it refuses (401). */
49
+ const PROBE_DATASET$1 = "holocron-token-check";
50
+ /** The `logs` capability for Axiom: checks a dataset is reachable and creates datasets that are missing. */
11
51
  var AxiomLogs = class {
12
52
  client;
13
53
  opts;
54
+ /** The capability key, always `logs`. */
14
55
  key = "logs";
56
+ /** The provider name, `axiom`. */
15
57
  providerName = "axiom";
16
58
  /**
17
59
  * `client` is a thunk — the token is resolved on first call, so
@@ -30,52 +72,259 @@ var AxiomLogs = class {
30
72
  async whoami() {
31
73
  const dataset = this.opts.dataset;
32
74
  if (!dataset) throw new Error("@theholocron/holocron-plugin-axiom needs a dataset (HOLOCRON_AXIOM_DATASET / AXIOM_DATASET) for whoami");
33
- await this.client().getDataset(dataset);
75
+ await this.client().datasets.get(dataset);
34
76
  return {
35
77
  ok: true,
36
78
  dataset
37
79
  };
38
80
  }
81
+ async readDataset(name) {
82
+ try {
83
+ const found = await this.client().datasets.get(name);
84
+ const days = found.useRetentionPeriod === false ? void 0 : found.retentionDays;
85
+ return {
86
+ exists: true,
87
+ ...days === void 0 ? {} : { retentionDays: days }
88
+ };
89
+ } catch (err) {
90
+ if (err instanceof ProviderApiError && err.status === 404) return { exists: false };
91
+ throw err;
92
+ }
93
+ }
94
+ async checkToken() {
95
+ try {
96
+ await this.client().datasets.get(PROBE_DATASET$1);
97
+ return { ok: true };
98
+ } catch (err) {
99
+ if (err instanceof ProviderApiError) {
100
+ if (err.status === 404) return { ok: true };
101
+ if (err.status === 401) return {
102
+ ok: false,
103
+ reason: "Axiom refused the token (401)"
104
+ };
105
+ }
106
+ throw err;
107
+ }
108
+ }
39
109
  async ensureDataset(name) {
40
110
  try {
41
- await this.client().getDataset(name);
111
+ await this.client().datasets.get(name);
42
112
  return { alreadyExists: true };
43
113
  } catch (err) {
44
114
  if (!(err instanceof ProviderApiError) || err.status !== 404) throw err;
45
115
  }
46
- await this.client().createDataset({
116
+ await this.client().datasets.create({
47
117
  name,
48
118
  description: "Managed by holocron"
49
119
  });
50
120
  return { alreadyExists: false };
51
121
  }
52
122
  };
53
- function createAxiomClient(opts) {
54
- const rest = createRestClient({
55
- baseUrl: opts.baseUrl ?? "https://api.axiom.co",
56
- token: opts.token,
57
- vendor: "Axiom",
58
- fetch: opts.fetch
59
- });
123
+ // src/probes/token/parse-token-args.ts
124
+ /** Reads the words after the probe name: `--layer <word>`, `--token-name <VAR>` and any number of dataset names. */
125
+ function parseTokenArgs(args) {
126
+ const datasets = [];
127
+ let layer;
128
+ let tokenName;
129
+ for (let i = 0; i < args.length; i++) {
130
+ const arg = args[i];
131
+ if (arg === "--layer") layer = args[++i];
132
+ else if (arg.startsWith("--layer=")) layer = arg.slice(8);
133
+ else if (arg === "--token-name") tokenName = args[++i];
134
+ else if (arg.startsWith("--token-name=")) tokenName = arg.slice(13);
135
+ else if (!arg.startsWith("--")) datasets.push(arg);
136
+ }
137
+ return {
138
+ ...layer ? { layer } : {},
139
+ ...tokenName ? { tokenName } : {},
140
+ datasets
141
+ };
142
+ }
143
+ // src/probes/token/token.ts
144
+ /** How many names to show before "(+N more)". */
145
+ const SHOWN = 8;
146
+ /** The time a query looks back over: a minute is enough, the query reads nothing the probe prints. */
147
+ const QUERY_WINDOW_MS = 6e4;
148
+ /** `a, b, c (+2 more)`. */
149
+ function summarise(names) {
150
+ return names.length <= SHOWN ? names.join(", ") : `${names.slice(0, SHOWN).join(", ")} (+${names.length - SHOWN} more)`;
151
+ }
152
+ /**
153
+ * Runs one request and says what came back. Axiom answers a token without the permission with a 401 or 403, and a
154
+ * dataset the token cannot see (or that does not exist) with a 404; all three are `none`. A request that fails for
155
+ * another reason (the network, a 5xx) is an `error`.
156
+ */
157
+ async function reach(request) {
158
+ try {
159
+ await request();
160
+ return { kind: "has" };
161
+ } catch (err) {
162
+ if (err instanceof ProviderApiError && (err.status === 401 || err.status === 403)) return {
163
+ kind: "none",
164
+ detail: `no access (${err.status})`
165
+ };
166
+ if (err instanceof ProviderApiError && err.status === 404) return {
167
+ kind: "none",
168
+ detail: "no such dataset, or the token cannot see it (404)"
169
+ };
170
+ return {
171
+ kind: "error",
172
+ detail: errorMessage(err)
173
+ };
174
+ }
175
+ }
176
+ /** The APL query that reads one row of a dataset; the name is quoted the way APL quotes an identifier. */
177
+ function queryFor(dataset) {
178
+ return `['${dataset.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'] | take 1`;
179
+ }
180
+ /**
181
+ * One row for what was tried. With no rule it only describes (`ok` for access, `info` for none). Under a layer's rule it
182
+ * judges: a required permission the token lacks fails, and one the layer must not have fails when the token has it; a
183
+ * permission that is rightly absent is a bare `ok`.
184
+ */
185
+ function rowFor({ label, outcome }, rule) {
186
+ const detail = outcome.detail === void 0 ? {} : { detail: outcome.detail };
187
+ if (outcome.kind === "error") return {
188
+ status: "fail",
189
+ label,
190
+ ...detail
191
+ };
192
+ const has = outcome.kind === "has";
193
+ if (rule === "required") return {
194
+ status: has ? "ok" : "fail",
195
+ label,
196
+ ...detail
197
+ };
198
+ if (rule === "absent") return has ? {
199
+ status: "fail",
200
+ label,
201
+ ...detail
202
+ } : {
203
+ status: "ok",
204
+ label
205
+ };
60
206
  return {
61
- getDataset: (name) => rest.request(`/v2/datasets/${encodeURIComponent(name)}`),
62
- createDataset: (input) => rest.request("/v2/datasets", {
63
- method: "POST",
64
- body: input
65
- }),
66
- getCurrentUser: () => rest.request("/v2/user")
207
+ status: has ? "ok" : "info",
208
+ label,
209
+ ...detail
67
210
  };
68
211
  }
69
- //#endregion
70
- //#region src/verify-token.ts
71
212
  /**
72
- * `verifyToken` — plugin-level export used by `holocron auth set axiom`
73
- * + `holocron auth check`. Hits `GET /v2/user` and translates the
213
+ * The `token` probe: tries each permission Holocron uses with the Axiom token on a dataset (reading it, ingesting and
214
+ * querying) and reports which ones the token has, then lists the datasets the token can see, so a token that reaches a
215
+ * retired dataset (`holocron-local`) is visible. Ingesting sends an empty list, which writes no event, and the query
216
+ * reads one row it never prints, so the probe changes nothing. The token is the one the plugin resolves, so
217
+ * `--token axiom=<token>` or `--environment <layer>` checks another one; the dataset is the plugin's own, or the names
218
+ * after the probe name.
219
+ *
220
+ * A token with no layer is only described. When the CLI passes `--layer` (because `--environment` named `ci`, `dev` or
221
+ * `local`), the results are judged against what that layer's token is meant to carry (the plugin's `tokens` declaration,
222
+ * read with `tokenExpectations()`) and shown in two groups, what it should have and what it should not, where a
223
+ * missing or extra permission fails.
224
+ */
225
+ function tokenProbe(ctx) {
226
+ return {
227
+ summary: "Try each Axiom permission Holocron uses (read, ingest, query) on a dataset with a token, and list the datasets the token can see; for a ci or dev Environment, check it against what that layer should carry. Read-only: ingest sends no event.",
228
+ writes: false,
229
+ acceptsToken: true,
230
+ async run(probe) {
231
+ const token = ctx.token();
232
+ probe.secret(token);
233
+ const client = ctx.client();
234
+ const { layer, tokenName, datasets: named } = parseTokenArgs(probe.args ?? []);
235
+ const rules = layer ? tokenExpectations(tokens, {
236
+ layer,
237
+ ...tokenName ? { envName: tokenName } : {}
238
+ })[0]?.rules : void 0;
239
+ if (layer && !rules) probe.say({
240
+ status: "info",
241
+ label: layer,
242
+ detail: "no expectations are declared for it, so the token is only described"
243
+ });
244
+ const targets = named.length > 0 ? named : ctx.options.dataset ? [ctx.options.dataset] : [];
245
+ if (targets.length === 0) probe.say({
246
+ status: rules ? "fail" : "info",
247
+ label: "dataset",
248
+ detail: "none given: name one after the probe, or set HOLOCRON_AXIOM_DATASET or the plugin's dataset option"
249
+ });
250
+ const tried = [];
251
+ for (const dataset of targets) {
252
+ const now = Date.now();
253
+ tried.push({
254
+ label: `Read (${dataset})`,
255
+ permission: "read",
256
+ outcome: await reach(() => client.datasets.get(dataset))
257
+ }, {
258
+ label: `Ingest (${dataset})`,
259
+ permission: "ingest",
260
+ outcome: await reach(() => client.datasets.ingest(dataset, []))
261
+ }, {
262
+ label: `Query (${dataset})`,
263
+ permission: "query",
264
+ outcome: await reach(() => client.datasets.query({
265
+ apl: queryFor(dataset),
266
+ startTime: (/* @__PURE__ */ new Date(now - QUERY_WINDOW_MS)).toISOString(),
267
+ endTime: new Date(now).toISOString()
268
+ }))
269
+ });
270
+ }
271
+ if (!rules) for (const t of tried) probe.say(rowFor(t, void 0));
272
+ else for (const [heading, rule] of [["Should have", "required"], ["Should not have", "absent"]]) {
273
+ const inGroup = tried.filter((t) => rules[t.permission] === rule);
274
+ if (inGroup.length === 0) continue;
275
+ probe.say({
276
+ status: "heading",
277
+ label: heading
278
+ });
279
+ for (const t of inGroup) probe.say(rowFor(t, rule));
280
+ }
281
+ probe.say({
282
+ status: "heading",
283
+ label: "Datasets this token can see"
284
+ });
285
+ try {
286
+ const names = (await client.datasets.list()).map((d) => d.name);
287
+ probe.say(names.length === 0 ? {
288
+ status: "info",
289
+ label: "datasets",
290
+ detail: "none visible"
291
+ } : {
292
+ status: "info",
293
+ label: "datasets",
294
+ detail: `${names.length}: ${summarise(names)}`
295
+ });
296
+ for (const name of names.filter((n) => RETIRED_DATASETS.includes(n))) probe.say({
297
+ status: "info",
298
+ label: name,
299
+ detail: "retired (one dataset per service now, ADR-0019): the token still reaches it"
300
+ });
301
+ } catch (err) {
302
+ const denied = err instanceof ProviderApiError && (err.status === 401 || err.status === 403);
303
+ probe.say({
304
+ status: denied ? "info" : "fail",
305
+ label: "datasets",
306
+ detail: denied ? `the token cannot list datasets (${err.status})` : errorMessage(err)
307
+ });
308
+ }
309
+ }
310
+ };
311
+ }
312
+ // src/verify-token.ts
313
+ /**
314
+ * `verifyToken` — plugin-level export used by `holocron new token axiom`
315
+ * + `holocron check token`. Hits `GET /v2/user` and translates the
74
316
  * response into the normalized `VerifyTokenResult` shape.
75
317
  *
76
318
  * Kept as a standalone function (not a capability method) so the auth
77
319
  * command can call it without initializing the full plugin.
78
320
  */
321
+ /** A dataset that does not exist: asking for it tells a token that may read datasets (404) from one that may not (403). */
322
+ const PROBE_DATASET = "holocron-token-check";
323
+ /**
324
+ * Checks an Axiom token by fetching the current user; the success subject is `user @` followed by the email, name or id,
325
+ * the failure carries the error message. An API token cannot read the user (403), so then it asks for a dataset that
326
+ * does not exist: a 404 means the token is accepted and may read datasets, and the subject says `API token`.
327
+ */
79
328
  async function verifyToken(token, opts = {}) {
80
329
  const client = createAxiomClient({
81
330
  token,
@@ -83,23 +332,42 @@ async function verifyToken(token, opts = {}) {
83
332
  fetch: opts.fetch
84
333
  });
85
334
  try {
86
- const me = await client.getCurrentUser();
335
+ const me = await client.user.me();
87
336
  return {
88
337
  ok: true,
89
338
  subject: `user @ ${me.email ?? me.emails?.[0] ?? me.name ?? me.id ?? "unknown"}`
90
339
  };
91
340
  } catch (err) {
341
+ if (err instanceof ProviderApiError && err.status === 403) return verifyApiToken(client);
342
+ return {
343
+ ok: false,
344
+ message: errorMessage(err)
345
+ };
346
+ }
347
+ }
348
+ async function verifyApiToken(client) {
349
+ try {
350
+ await client.datasets.get(PROBE_DATASET);
351
+ return {
352
+ ok: true,
353
+ subject: "API token"
354
+ };
355
+ } catch (err) {
356
+ if (err instanceof ProviderApiError && err.status === 404) return {
357
+ ok: true,
358
+ subject: "API token"
359
+ };
92
360
  return {
93
361
  ok: false,
94
- message: err instanceof Error ? err.message : String(err)
362
+ message: errorMessage(err)
95
363
  };
96
364
  }
97
365
  }
98
- //#endregion
99
- //#region src/index.ts
366
+ // src/index.ts
367
+ /** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
100
368
  function createContext(options) {
101
- const env = options.env ?? process.env;
102
- const dataset = options.dataset ?? env.HOLOCRON_AXIOM_DATASET ?? env.AXIOM_DATASET;
369
+ const env = createEnvLookup(options.env);
370
+ const dataset = options.dataset ?? firstEnv(env, ["HOLOCRON_AXIOM_DATASET", "AXIOM_DATASET"]);
103
371
  let client;
104
372
  return {
105
373
  options: {
@@ -113,20 +381,38 @@ function createContext(options) {
113
381
  })
114
382
  };
115
383
  }
384
+ /** Builds the `logs` capability from a plugin context. */
116
385
  function logs(ctx) {
117
386
  return new AxiomLogs(ctx.client, { dataset: ctx.options.dataset });
118
387
  }
388
+ /** Creates the Axiom plugin: the `connection` and `token` probes and the `logs` capability. */
119
389
  function createPlugin(options) {
120
390
  const ctx = createContext(options);
121
391
  return {
122
392
  name: "@theholocron/holocron-plugin-axiom",
393
+ probes: {
394
+ token: tokenProbe({
395
+ options: ctx.options,
396
+ client: ctx.client,
397
+ token: () => resolveToken(options)
398
+ }),
399
+ connection: connectionProbe({
400
+ provider: "Axiom",
401
+ url: options.baseUrl ?? "https://api.axiom.co",
402
+ fetch: options.fetch,
403
+ token: () => resolveToken(options),
404
+ verify: (token) => verifyToken(token, {
405
+ baseUrl: options.baseUrl,
406
+ fetch: options.fetch
407
+ })
408
+ })
409
+ },
123
410
  capabilities: { logs: () => logs(ctx) }
124
411
  };
125
412
  }
126
413
  /**
127
- * One-line hint shown by `holocron auth set axiom` when no token is
414
+ * One-line hint shown by `holocron new token axiom` when no token is
128
415
  * supplied or when the supplied token is rejected.
129
416
  */
130
- const AUTH_HINT = "generate an Axiom API token at https://app.axiom.co/settings/api-tokens with dataset read + create permissions, then run: holocron auth set axiom <TOKEN>";
131
- //#endregion
132
- export { AUTH_HINT, AuthError, AxiomLogs, createAxiomClient, createContext, createPlugin, logs, resolveToken, verifyToken };
417
+ const AUTH_HINT = "generate an Axiom API token at https://app.axiom.co/settings/api-tokens with dataset read + create permissions, then run: holocron new token axiom <TOKEN>";
418
+ export { AUTH_HINT, AuthError, AxiomLogs, createAxiomClient, createContext, createPlugin, logs, resolveToken, tokens, verifyToken };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-axiom",
3
- "version": "5.0.0-alpha.44",
3
+ "version": "5.0.0-alpha.441",
4
4
  "description": "Holocron plugin for Axiom. Implements the logs capability against Axiom's REST API — dataset provisioning and connectivity checks, plus verifyToken + AUTH_HINT for `holocron auth`.",
5
5
  "keywords": [
6
6
  "axiom",
@@ -8,12 +8,12 @@
8
8
  "logs",
9
9
  "plugin"
10
10
  ],
11
- "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-axiom#readme",
11
+ "homepage": "https://docs.theholocron.dev/holocron/plugins/axiom/",
12
12
  "bugs": "https://github.com/theholocron/holocron/issues",
13
13
  "repository": {
14
14
  "type": "git",
15
15
  "url": "git+https://github.com/theholocron/holocron.git",
16
- "directory": "packages/holocron-plugin-axiom"
16
+ "directory": "plugins/holocron-plugin-axiom"
17
17
  },
18
18
  "license": "MIT",
19
19
  "author": "Newton Koumantzelis",
@@ -29,26 +29,33 @@
29
29
  "files": [
30
30
  "dist"
31
31
  ],
32
+ "dependencies": {
33
+ "@theholocron/env-utils": "^1.17.0-alpha.4"
34
+ },
32
35
  "devDependencies": {
33
- "@theholocron/eslint-config": "^8.4.5",
34
- "@theholocron/http-client": "^1.25.0",
35
- "@theholocron/tsconfig": "^8.4.5",
36
- "@theholocron/tsdown-config": "^8.4.5",
37
- "@theholocron/vitest-config": "^8.4.5",
38
36
  "@types/node": "^26",
39
- "@vitest/coverage-v8": "^4.1.11",
40
- "@vitest/eslint-plugin": "^1.6.27",
41
- "eslint": "^10.8.1",
42
- "eslint-plugin-n": "^18.3.0",
43
- "globals": "^17.11.0",
44
- "tsdown": "^0.22.14",
45
- "tsx": "4.23.12",
37
+ "@vitest/coverage-v8": "^5.1.0",
38
+ "@vitest/eslint-plugin": "^1.6.28",
39
+ "eslint": "^10.14.0",
40
+ "eslint-plugin-n": "^18.5.0",
41
+ "globals": "^17.14.0",
42
+ "tsdown": "^0.23.5",
43
+ "tsx": "4.23.15",
46
44
  "typescript": "^5.9.3",
47
- "vitest": "^4.1.11",
48
- "@theholocron/cli": "5.0.0-alpha.44"
45
+ "vitest": "^5.1.0",
46
+ "@theholocron/axiom-client": "^1.58.0-alpha.32",
47
+ "@theholocron/cli": "5.0.0-alpha.441",
48
+ "@theholocron/eslint-config": "^8.9.0-alpha.17",
49
+ "@theholocron/http-client": "^1.58.0-alpha.32",
50
+ "@theholocron/tsconfig": "^8.9.0-alpha.17",
51
+ "@theholocron/tsdown-config": "^8.9.0-alpha.17",
52
+ "@theholocron/vitest-config": "^8.9.0-alpha.17",
53
+ "@theholocron/misc-utils": "^1.17.0-alpha.4"
49
54
  },
50
55
  "peerDependencies": {
51
- "@theholocron/cli": "5.0.0-alpha.44"
56
+ "@theholocron/axiom-client": "^1.43.1",
57
+ "@theholocron/misc-utils": "^1.16.0",
58
+ "@theholocron/cli": "5.0.0-alpha.441"
52
59
  },
53
60
  "engines": {
54
61
  "node": ">=22"
@@ -57,11 +64,11 @@
57
64
  "access": "public"
58
65
  },
59
66
  "scripts": {
60
- "delivery.build": "tsdown",
61
- "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
67
+ "build": "tsdown",
68
+ "lint:code": "eslint .",
69
+ "test:unit": "vitest run --coverage",
62
70
  "test:watch": "vitest",
63
- "validate": "tsx scripts/validate.mjs",
64
- "verification.typeSafety": "holocron run verification.typeSafety --",
65
- "verification.unitTests": "holocron run verification.unitTests --"
71
+ "typecheck": "tsc --noEmit",
72
+ "validate:plugin": "tsx scripts/validate.mjs"
66
73
  }
67
74
  }