@theholocron/holocron-plugin-axiom 5.0.0-alpha.37 → 5.0.0-alpha.371

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
@@ -9,7 +9,7 @@ plus exports `verifyToken` + `AUTH_HINT` for use by `holocron auth`.
9
9
  > This plugin does **not** ship log lines. `@theholocron/observability/logger`'s
10
10
  > Axiom transport reads `HOLOCRON_AXIOM_TOKEN` / `HOLOCRON_AXIOM_DATASET`
11
11
  > directly at startup. The `logs` capability exists only for the
12
- > management surface — `holocron setup` provisions the aggregation
12
+ > management surface — `holocron repo setup` provisions the aggregation
13
13
  > datasets and `holocron doctor` checks connectivity.
14
14
 
15
15
  ## Install
@@ -49,15 +49,14 @@ 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 repo 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
 
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, 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 tokens`. */
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[];
@@ -64,39 +38,26 @@ declare class AxiomLogs implements Logs {
64
38
  alreadyExists: boolean;
65
39
  }>;
66
40
  }
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
41
  interface VerifyTokenOptions {
87
42
  baseUrl?: string;
88
43
  fetch?: typeof fetch;
89
44
  }
90
- declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
91
- //#endregion
92
- //#region src/index.d.ts
93
- interface AxiomPluginOptions extends ResolveTokenInput, AxiomLogsOptions {
45
+ /**
46
+ * Checks an Axiom token by fetching the current user; the success subject is `user @` followed by the email, name or id,
47
+ * the failure carries the error message. An API token cannot read the user (403), so then it asks for a dataset that
48
+ * does not exist: a 404 means the token is accepted and may read datasets, and the subject says `API token`.
49
+ */
50
+ export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
51
+ /** Options for the Axiom plugin: token resolution, the target dataset and test overrides. */
52
+ export interface AxiomPluginOptions extends ResolveTokenInput, AxiomLogsOptions {
94
53
  /** Override base URL for tests. */
95
54
  baseUrl?: string;
96
55
  /** Override `fetch` for tests. */
97
56
  fetch?: typeof fetch;
98
57
  }
99
- interface PluginContext {
58
+ /** What the plugin's capabilities share: the resolved options and a lazily built client. */
59
+ export interface PluginContext {
60
+ /** The options, with `dataset` resolved from config, `HOLOCRON_AXIOM_DATASET` or `AXIOM_DATASET` (in that order). */
100
61
  options: AxiomPluginOptions & {
101
62
  dataset?: string;
102
63
  };
@@ -106,12 +67,18 @@ interface PluginContext {
106
67
  * no auth (`describe`) works without a token, and the loader never
107
68
  * aborts on a plugin whose token happens to be absent.
108
69
  */
109
- client: () => AxiomRestClient;
70
+ client: () => AxiomClient;
110
71
  }
111
- declare function createContext(options: AxiomPluginOptions): PluginContext;
112
- declare function logs(ctx: PluginContext): Logs;
113
- declare function createPlugin(options: AxiomPluginOptions): {
72
+ /** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
73
+ export declare function createContext(options: AxiomPluginOptions): PluginContext;
74
+ /** Builds the `logs` capability from a plugin context. */
75
+ export declare function logs(ctx: PluginContext): Logs;
76
+ /** Creates the Axiom plugin: a `connection` probe and the `logs` capability. */
77
+ export declare function createPlugin(options: AxiomPluginOptions): {
114
78
  name: string;
79
+ probes: {
80
+ connection: import("@theholocron/cli").Probe;
81
+ };
115
82
  capabilities: {
116
83
  logs: () => Logs;
117
84
  };
@@ -120,6 +87,5 @@ declare function createPlugin(options: AxiomPluginOptions): {
120
87
  * One-line hint shown by `holocron auth set axiom` when no token is
121
88
  * supplied or when the supplied token is rejected.
122
89
  */
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 };
90
+ export declare const AUTH_HINT: string;
91
+ 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,25 @@
1
- import { AuthError, ProviderApiError, createResolveToken, createRestClient } from "@theholocron/cli";
2
- //#region src/auth.ts
1
+ import { AuthError, ProviderApiError, connectionProbe, createResolveToken } from "@theholocron/cli";
2
+ import { createEnvLookup, firstEnv } from "@theholocron/env-utils/lookup";
3
+ import { createAxiomClient } from "@theholocron/axiom-client";
4
+ import { errorMessage } from "@theholocron/misc-utils";
5
+ // src/auth.ts
6
+ /** Resolves the Axiom token from `--token`, `HOLOCRON_AXIOM_TOKEN`, `AXIOM_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
3
7
  const resolveToken = createResolveToken({
4
8
  envName: "HOLOCRON_AXIOM_TOKEN",
5
9
  vendorEnvName: "AXIOM_TOKEN",
6
10
  keyringService: "axiom",
7
11
  errorMessage: "no Axiom token found. Pass --token <TOKEN>, set HOLOCRON_AXIOM_TOKEN / AXIOM_TOKEN, or run: holocron auth set axiom <TOKEN>"
8
12
  });
9
- //#endregion
10
- //#region src/capabilities/logs.ts
13
+ /** Every token this plugin takes, for `holocron doctor tokens`. */
14
+ const tokens = [resolveToken.token];
15
+ // src/capabilities/logs.ts
16
+ /** The `logs` capability for Axiom: checks a dataset is reachable and creates datasets that are missing. */
11
17
  var AxiomLogs = class {
12
18
  client;
13
19
  opts;
20
+ /** The capability key, always `logs`. */
14
21
  key = "logs";
22
+ /** The provider name, `axiom`. */
15
23
  providerName = "axiom";
16
24
  /**
17
25
  * `client` is a thunk — the token is resolved on first call, so
@@ -30,7 +38,7 @@ var AxiomLogs = class {
30
38
  async whoami() {
31
39
  const dataset = this.opts.dataset;
32
40
  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);
41
+ await this.client().datasets.get(dataset);
34
42
  return {
35
43
  ok: true,
36
44
  dataset
@@ -38,36 +46,19 @@ var AxiomLogs = class {
38
46
  }
39
47
  async ensureDataset(name) {
40
48
  try {
41
- await this.client().getDataset(name);
49
+ await this.client().datasets.get(name);
42
50
  return { alreadyExists: true };
43
51
  } catch (err) {
44
52
  if (!(err instanceof ProviderApiError) || err.status !== 404) throw err;
45
53
  }
46
- await this.client().createDataset({
54
+ await this.client().datasets.create({
47
55
  name,
48
56
  description: "Managed by holocron"
49
57
  });
50
58
  return { alreadyExists: false };
51
59
  }
52
60
  };
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
- });
60
- 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")
67
- };
68
- }
69
- //#endregion
70
- //#region src/verify-token.ts
61
+ // src/verify-token.ts
71
62
  /**
72
63
  * `verifyToken` — plugin-level export used by `holocron auth set axiom`
73
64
  * + `holocron auth check`. Hits `GET /v2/user` and translates the
@@ -76,6 +67,13 @@ function createAxiomClient(opts) {
76
67
  * Kept as a standalone function (not a capability method) so the auth
77
68
  * command can call it without initializing the full plugin.
78
69
  */
70
+ /** A dataset that does not exist: asking for it tells a token that may read datasets (404) from one that may not (403). */
71
+ const PROBE_DATASET = "holocron-token-check";
72
+ /**
73
+ * Checks an Axiom token by fetching the current user; the success subject is `user @` followed by the email, name or id,
74
+ * the failure carries the error message. An API token cannot read the user (403), so then it asks for a dataset that
75
+ * does not exist: a 404 means the token is accepted and may read datasets, and the subject says `API token`.
76
+ */
79
77
  async function verifyToken(token, opts = {}) {
80
78
  const client = createAxiomClient({
81
79
  token,
@@ -83,23 +81,42 @@ async function verifyToken(token, opts = {}) {
83
81
  fetch: opts.fetch
84
82
  });
85
83
  try {
86
- const me = await client.getCurrentUser();
84
+ const me = await client.user.me();
87
85
  return {
88
86
  ok: true,
89
87
  subject: `user @ ${me.email ?? me.emails?.[0] ?? me.name ?? me.id ?? "unknown"}`
90
88
  };
91
89
  } catch (err) {
90
+ if (err instanceof ProviderApiError && err.status === 403) return verifyApiToken(client);
91
+ return {
92
+ ok: false,
93
+ message: errorMessage(err)
94
+ };
95
+ }
96
+ }
97
+ async function verifyApiToken(client) {
98
+ try {
99
+ await client.datasets.get(PROBE_DATASET);
100
+ return {
101
+ ok: true,
102
+ subject: "API token"
103
+ };
104
+ } catch (err) {
105
+ if (err instanceof ProviderApiError && err.status === 404) return {
106
+ ok: true,
107
+ subject: "API token"
108
+ };
92
109
  return {
93
110
  ok: false,
94
- message: err instanceof Error ? err.message : String(err)
111
+ message: errorMessage(err)
95
112
  };
96
113
  }
97
114
  }
98
- //#endregion
99
- //#region src/index.ts
115
+ // src/index.ts
116
+ /** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
100
117
  function createContext(options) {
101
- const env = options.env ?? process.env;
102
- const dataset = options.dataset ?? env.HOLOCRON_AXIOM_DATASET ?? env.AXIOM_DATASET;
118
+ const env = createEnvLookup(options.env);
119
+ const dataset = options.dataset ?? firstEnv(env, ["HOLOCRON_AXIOM_DATASET", "AXIOM_DATASET"]);
103
120
  let client;
104
121
  return {
105
122
  options: {
@@ -113,13 +130,25 @@ function createContext(options) {
113
130
  })
114
131
  };
115
132
  }
133
+ /** Builds the `logs` capability from a plugin context. */
116
134
  function logs(ctx) {
117
135
  return new AxiomLogs(ctx.client, { dataset: ctx.options.dataset });
118
136
  }
137
+ /** Creates the Axiom plugin: a `connection` probe and the `logs` capability. */
119
138
  function createPlugin(options) {
120
139
  const ctx = createContext(options);
121
140
  return {
122
141
  name: "@theholocron/holocron-plugin-axiom",
142
+ probes: { connection: connectionProbe({
143
+ provider: "Axiom",
144
+ url: options.baseUrl ?? "https://api.axiom.co",
145
+ fetch: options.fetch,
146
+ token: () => resolveToken(options),
147
+ verify: (token) => verifyToken(token, {
148
+ baseUrl: options.baseUrl,
149
+ fetch: options.fetch
150
+ })
151
+ }) },
123
152
  capabilities: { logs: () => logs(ctx) }
124
153
  };
125
154
  }
@@ -128,5 +157,4 @@ function createPlugin(options) {
128
157
  * supplied or when the supplied token is rejected.
129
158
  */
130
159
  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 };
160
+ 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.37",
3
+ "version": "5.0.0-alpha.371",
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.2"
34
+ },
32
35
  "devDependencies": {
33
- "@theholocron/eslint-config": "^8.0.0",
34
- "@theholocron/http-client": "^1.24.0",
35
- "@theholocron/tsconfig": "^8.0.0",
36
- "@theholocron/tsdown-config": "^8.0.0",
37
- "@theholocron/vitest-config": "^8.0.0",
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.37"
45
+ "vitest": "^5.1.0",
46
+ "@theholocron/axiom-client": "^1.58.0-alpha.18",
47
+ "@theholocron/cli": "5.0.0-alpha.371",
48
+ "@theholocron/http-client": "^1.58.0-alpha.18",
49
+ "@theholocron/eslint-config": "^8.9.0-alpha.11",
50
+ "@theholocron/misc-utils": "^1.17.0-alpha.2",
51
+ "@theholocron/tsconfig": "^8.9.0-alpha.11",
52
+ "@theholocron/tsdown-config": "^8.9.0-alpha.11",
53
+ "@theholocron/vitest-config": "^8.9.0-alpha.11"
49
54
  },
50
55
  "peerDependencies": {
51
- "@theholocron/cli": "5.0.0-alpha.37"
56
+ "@theholocron/axiom-client": "^1.43.1",
57
+ "@theholocron/misc-utils": "^1.16.0",
58
+ "@theholocron/cli": "5.0.0-alpha.371"
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
  }