@theholocron/cli 5.0.0-alpha.426 → 5.0.0-alpha.428

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/dist/cli.mjs CHANGED
@@ -19749,6 +19749,21 @@ const newCommand = {
19749
19749
  handler: () => {}
19750
19750
  };
19751
19751
  // src/commands/probe/probe.args.ts
19752
+ /**
19753
+ * Shown in `holocron probe --help`: how a probe about a token (`cloudflare token`) picks the token it checks, so the
19754
+ * run itself prints only the result.
19755
+ */
19756
+ const TOKEN_PROBE_HELP = [
19757
+ "Probes about a token (for example `holocron probe cloudflare token`) check one token. The first of these that applies picks it:",
19758
+ [
19759
+ "- --token <provider>=<value>: that token (a bare --token <value> goes to every provider).",
19760
+ "- --environment <layer or name>: the provider's token, read from that vault Environment.",
19761
+ "- On a terminal, with neither: a question, which asks for the configured token, an Environment or a pasted token.",
19762
+ "- Otherwise: the token the provider normally resolves."
19763
+ ].join("\n"),
19764
+ "--environment takes a layer (local, dev, ci or prod, which is this repo's `<org/repo> - <layer>`) or an Environment the config already names; anything else is refused. `local` is read over `dev`, as the CLI reads it.",
19765
+ "A token read from a layer is checked against what that layer's token should carry (the permission table in the tokens docs): what it should have must be there and what it should not have must not be. Any other token is only described. The token is never printed."
19766
+ ].join("\n\n");
19752
19767
  const probeArgs = (y) => y.positional("provider", {
19753
19768
  type: "string",
19754
19769
  describe: "Which provider's probes (omit to list them all)"
@@ -19783,7 +19798,7 @@ const probeArgs = (y) => y.positional("provider", {
19783
19798
  type: "boolean",
19784
19799
  default: false,
19785
19800
  describe: "Run a probe that changes things without asking first (required without a terminal)"
19786
- });
19801
+ }).epilogue(TOKEN_PROBE_HELP);
19787
19802
  // src/commands/probe/app-vault.ts
19788
19803
  /**
19789
19804
  * The vault of an app that carries its own `holocron.config` (`apps/comlink`, `apps/sentinel`): those configs govern where
@@ -20567,6 +20582,147 @@ function realDocsPresenceIo(repoRoot) {
20567
20582
  };
20568
20583
  /* v8 ignore stop */
20569
20584
  }
20585
+ // src/commands/token-expectations/token-expectations.ts
20586
+ /**
20587
+ * Reads what a plugin's tokens declare (`PluginToken.expect`) as one entry per token and layer that holds it, in the
20588
+ * order of `ENVIRONMENT_LAYERS`. The one reader the token probes, the doctor and the docs check share, so none of them
20589
+ * walks the declaration itself. A token with no `expect` yields nothing; a layer no token holds is never listed.
20590
+ */
20591
+ function tokenExpectations(tokens, filter = {}) {
20592
+ const found = [];
20593
+ for (const token of tokens) {
20594
+ if (!token.expect || filter.envName !== void 0 && token.envName !== filter.envName) continue;
20595
+ const { layers = [], permissions = {} } = token.expect;
20596
+ for (const layer of ENVIRONMENT_LAYERS) {
20597
+ if (filter.layer !== void 0 && filter.layer !== layer) continue;
20598
+ const rules = permissions[layer];
20599
+ if (!rules && !layers.includes(layer)) continue;
20600
+ const entries = Object.entries(rules ?? {});
20601
+ found.push({
20602
+ envName: token.envName,
20603
+ layer,
20604
+ rules: rules ?? {},
20605
+ required: entries.filter(([, rule]) => rule === "required").map(([name]) => name),
20606
+ absent: entries.filter(([, rule]) => rule === "absent").map(([name]) => name)
20607
+ });
20608
+ }
20609
+ }
20610
+ return found;
20611
+ }
20612
+ // src/commands/probe/docs-tokens/compare-permissions/compare-permissions.ts
20613
+ const mentions = (heading, name) => heading.toLowerCase().includes(name.toLowerCase());
20614
+ /**
20615
+ * Compares what a plugin's tokens declare (`PluginToken.expect.permissions`, read through `tokenExpectations()`) with its
20616
+ * permission table in `tokens.mdx`, in both directions: a declared permission the table lacks or words differently for
20617
+ * a layer, and a permission or layer rule the table has that the declaration does not. The table is the one whose
20618
+ * heading names the token's `envName`, else the plugin (`short`, `cloudflare` for `holocron-plugin-cloudflare`). A token
20619
+ * that declares no permission rules is not compared.
20620
+ */
20621
+ function comparePermissions(tokens, tables, short) {
20622
+ const problems = [];
20623
+ for (const token of tokens) {
20624
+ const declared = tokenExpectations([token]).filter((entry) => Object.keys(entry.rules).length > 0);
20625
+ if (declared.length === 0) continue;
20626
+ const { envName } = token;
20627
+ const table = tables.find((t) => mentions(t.heading, envName)) ?? tables.find((t) => mentions(t.heading, short));
20628
+ if (!table) {
20629
+ problems.push({
20630
+ envName,
20631
+ layer: "any",
20632
+ permission: "",
20633
+ detail: "no permission table in tokens.mdx"
20634
+ });
20635
+ continue;
20636
+ }
20637
+ const byLayer = new Map(declared.map((entry) => [entry.layer, Object.fromEntries(Object.entries(entry.rules).map(([id, rule]) => [id.toLowerCase(), rule]))]));
20638
+ const ids = new Set([...byLayer.values()].flatMap((rules) => Object.keys(rules)));
20639
+ for (const entry of declared) for (const [permission, rule] of Object.entries(entry.rules)) {
20640
+ const documented = table.rows[permission.toLowerCase()];
20641
+ if (!documented) problems.push({
20642
+ envName,
20643
+ layer: entry.layer,
20644
+ permission,
20645
+ detail: "not in the tokens.mdx table"
20646
+ });
20647
+ else if (documented[entry.layer] !== rule) problems.push({
20648
+ envName,
20649
+ layer: entry.layer,
20650
+ permission,
20651
+ detail: `declared ${rule}, tokens.mdx says ${documented[entry.layer] ?? "nothing"}`
20652
+ });
20653
+ }
20654
+ for (const [permission, documented] of Object.entries(table.rows)) {
20655
+ if (!ids.has(permission)) {
20656
+ problems.push({
20657
+ envName,
20658
+ layer: "any",
20659
+ permission,
20660
+ detail: "in the tokens.mdx table, not declared"
20661
+ });
20662
+ continue;
20663
+ }
20664
+ for (const [layer, rule] of Object.entries(documented)) if (byLayer.get(layer)?.[permission] === void 0) problems.push({
20665
+ envName,
20666
+ layer,
20667
+ permission,
20668
+ detail: `tokens.mdx says ${rule}, nothing declared`
20669
+ });
20670
+ }
20671
+ }
20672
+ return problems;
20673
+ }
20674
+ // src/commands/probe/docs-tokens/permission-tables/permission-tables.ts
20675
+ const clean = (cell) => cell.replace(/[`*_]/g, "").trim().toLowerCase();
20676
+ function cells(line) {
20677
+ return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
20678
+ }
20679
+ const isTableLine = (line) => line !== void 0 && line.trim().startsWith("|");
20680
+ const isSeparator = (line) => isTableLine(line) && /^[\s|:-]+$/.test(line);
20681
+ function rule(cell) {
20682
+ const word = clean(cell ?? "");
20683
+ return word === "required" || word === "absent" ? word : void 0;
20684
+ }
20685
+ /**
20686
+ * Reads the permission tables of `tokens.mdx`: a table whose header has an `Id` column and a column named for a layer
20687
+ * (`local`, `dev`, `ci`, `prod`). A cell says `required` or `absent`; anything else (a dash, blank) is no rule. Other
20688
+ * tables, extra columns and prose around a table are ignored, so a page can grow rows and columns without a change here.
20689
+ */
20690
+ function permissionTables(page) {
20691
+ const lines = page.split("\n");
20692
+ const tables = [];
20693
+ let heading = "";
20694
+ for (let i = 0; i < lines.length; i++) {
20695
+ const line = lines[i];
20696
+ const title = /^#{1,6}\s+(.*)$/.exec(line);
20697
+ if (title) heading = title[1].trim();
20698
+ if (!isTableLine(line) || !isSeparator(lines[i + 1])) continue;
20699
+ const header = cells(line).map(clean);
20700
+ const idColumn = header.indexOf("id");
20701
+ const layerColumns = ENVIRONMENT_LAYERS.map((layer) => [layer, header.indexOf(layer)]).filter(([, column]) => column >= 0);
20702
+ let end = i + 2;
20703
+ while (isTableLine(lines[end])) end++;
20704
+ if (idColumn >= 0 && layerColumns.length > 0) {
20705
+ const rows = {};
20706
+ for (const row of lines.slice(i + 2, end)) {
20707
+ const values = cells(row);
20708
+ const id = clean(values[idColumn] ?? "");
20709
+ if (id === "") continue;
20710
+ const documented = {};
20711
+ for (const [layer, column] of layerColumns) {
20712
+ const found = rule(values[column]);
20713
+ if (found) documented[layer] = found;
20714
+ }
20715
+ rows[id] = documented;
20716
+ }
20717
+ tables.push({
20718
+ heading,
20719
+ rows
20720
+ });
20721
+ }
20722
+ i = end - 1;
20723
+ }
20724
+ return tables;
20725
+ }
20570
20726
  // src/commands/probe/docs-tokens/docs-tokens-probe.ts
20571
20727
  const KEYS = [
20572
20728
  "envName",
@@ -20587,7 +20743,10 @@ function declared(text, keys) {
20587
20743
  * `keyringKey` in `plugins/<name>/src/auth.ts`) that `docs/src/content/docs/tokens.mdx` does not document. The Discord
20588
20744
  * and GitHub plugins have their own tables, so any row of the page counts; every other plugin has one row in the
20589
20745
  * provider table and its names must be in that row. A plugin that resolves nothing (1Password uses the `op` CLI's own
20590
- * auth) needs no row. The one resolver the setup command builds itself is checked against the whole page. It runs in
20746
+ * auth) needs no row. The one resolver the setup command builds itself is checked against the whole page. A token that
20747
+ * declares permissions per layer (`PluginToken.expect`, #2150) is also compared with its permission table, a table with
20748
+ * an `Id` column and a column per layer (`required` or `absent`): a permission, layer or rule that differs fails, naming
20749
+ * the token, layer and permission. A plugin whose declaration cannot be loaded (not built) is an `info` row. It runs in
20591
20750
  * the `validate:docs` task, through `docs validate`.
20592
20751
  */
20593
20752
  function docsTokensProbe(io) {
@@ -20642,6 +20801,39 @@ function docsTokensProbe(io) {
20642
20801
  label: "setup",
20643
20802
  detail: `${setupNames.length} documented`
20644
20803
  });
20804
+ ctx.say({
20805
+ status: "heading",
20806
+ label: "Documented permissions"
20807
+ });
20808
+ const tables = permissionTables(page);
20809
+ for (const { plugin, tokens, error } of await io.declarations()) {
20810
+ if (error !== void 0) {
20811
+ ctx.say({
20812
+ status: "info",
20813
+ label: plugin,
20814
+ detail: `declaration not loaded: ${error}`
20815
+ });
20816
+ continue;
20817
+ }
20818
+ const problems = comparePermissions(tokens, tables, plugin.replace("holocron-plugin-", ""));
20819
+ for (const { envName, layer, permission, detail } of problems) {
20820
+ const where = [
20821
+ envName,
20822
+ layer,
20823
+ permission
20824
+ ].filter((part) => part !== "").join(" ");
20825
+ ctx.say({
20826
+ status: "fail",
20827
+ label: where,
20828
+ detail
20829
+ });
20830
+ }
20831
+ if (problems.length === 0 && tokens.some((token) => token.expect?.permissions)) ctx.say({
20832
+ status: "ok",
20833
+ label: plugin,
20834
+ detail: "permissions match tokens.mdx"
20835
+ });
20836
+ }
20645
20837
  }
20646
20838
  };
20647
20839
  }
@@ -20658,6 +20850,24 @@ function realDocsTokensIo(repoRoot) {
20658
20850
  plugin,
20659
20851
  text: readFileSync(file, "utf8")
20660
20852
  })),
20853
+ declarations: async () => {
20854
+ const importer = createDefaultImporter(repoRoot);
20855
+ const plugins = readdirSync(join(repoRoot, "plugins")).filter((plugin) => existsSync(join(repoRoot, "plugins", plugin, "src/auth.ts")));
20856
+ return Promise.all(plugins.map(async (plugin) => {
20857
+ try {
20858
+ return {
20859
+ plugin,
20860
+ tokens: (await importer(`@theholocron/${plugin}`)).tokens ?? []
20861
+ };
20862
+ } catch (error) {
20863
+ return {
20864
+ plugin,
20865
+ tokens: [],
20866
+ error: error instanceof Error ? error.message : String(error)
20867
+ };
20868
+ }
20869
+ }));
20870
+ },
20661
20871
  setupSource: () => readFileSync(join(repoRoot, "cli/cli/src/commands/setup/run-setup.ts"), "utf8")
20662
20872
  };
20663
20873
  /* v8 ignore stop */
@@ -21990,7 +22200,7 @@ async function runProbeCommand(input) {
21990
22200
  let override;
21991
22201
  try {
21992
22202
  if (chosen?.environment) {
21993
- const found = await environmentToken({
22203
+ override = (await environmentToken({
21994
22204
  provider: input.provider,
21995
22205
  environment: chosen.environment,
21996
22206
  repoRoot: context.repoRoot,
@@ -21998,10 +22208,8 @@ async function runProbeCommand(input) {
21998
22208
  vault: loader.has("vault") ? loader.get("vault") : void 0,
21999
22209
  /* v8 ignore next -- the real importer reads installed plugin packages, which tests replace with `providerTokens` */
22000
22210
  tokens: await (input.providerTokens ?? defaultProviderTokens(input.loaded))(input.provider)
22001
- });
22002
- override = found.token;
22211
+ })).token;
22003
22212
  if (isEnvironmentLayer(chosen.environment)) layer = chosen.environment;
22004
- print(statusRow("skip", ["token", `read ${found.variable} from ${found.environment}`]));
22005
22213
  } else if (chosen?.token) override = chosen.token;
22006
22214
  } catch (err) {
22007
22215
  print(statusRow("fail", [`\`${input.provider} ${input.probe}\``, commandFailureMessage(err)]));