@metamask-previews/tooling-insight 1.0.1-preview-898fae5

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.1]
+
+### Added
+
+- Add preview build functionality to README and implement GitHub Actions workflow
+
+### Changed
+
+- Bump the npm_and_yarn group across 1 directory with 6 updates ([#4](https://github.com/MetaMask/experimental-tooling-insight/pull/4))
+
+### Fixed
+
+- Clear environment variables for isolated test runs in `run.test.ts`
+
+## [1.0.0]
+
+### Added
+
+- Initial implementation of the `metamask-daily-anonymizer` CLI binary ([#1](https://github.com/MetaMask/experimental-tooling-insight/pull/1))
+  - Reads local dev-tool event CSV logs from `~/.tool-usage-collection/`
+  - Folds raw events into per-day anonymized Prometheus counters
+  - Pushes to a Prometheus remote-write endpoint (Mimir) via a hand-rolled protobuf + snappy encoder with no runtime dependencies
+  - Supports `--dry-run`, `--force`, `--verbose`, and `--repo-root=<path>` CLI flags
+  - Maintains a state file to enforce a 24h push cadence and track the latest pushed day
+  - Published under the `alpha` npm dist-tag
+
+[Unreleased]: https://github.com/MetaMask/experimental-tooling-insight/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/MetaMask/experimental-tooling-insight/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/MetaMask/experimental-tooling-insight/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# `@metamask/tooling-insight`
+
+Daily anonymizer for MetaMask developer tooling usage metrics. Reads local dev-tool event logs, folds them into per-day anonymized counters, and pushes them to a Prometheus remote-write endpoint. Exposed as the `metamask-daily-anonymizer` CLI binary.
+
+## Installation
+
+`yarn add @metamask/tooling-insight`
+
+or
+
+`npm install @metamask/tooling-insight`
+
+## Usage
+
+Run the anonymizer directly:
+
+```bash
+metamask-daily-anonymizer [--dry-run] [--force] [--verbose] [--repo-root=<path>]
+```
+
+| Flag                 | Description                                                                                                                                                                      |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--dry-run`          | Print the exposition body without pushing or advancing state.                                                                                                                    |
+| `--force`            | Skip the 24 h cadence check and push regardless.                                                                                                                                 |
+| `--verbose`          | Write structured log output to stdout in addition to the log file.                                                                                                               |
+| `--repo-root=<path>` | Absolute path to the target repository. Used to resolve the skill/script allowlist and read `.js.env`. Defaults to the nearest `package.json` ancestor of the current directory. |
+
+Or import the `run` function programmatically:
+
+```typescript
+import { run } from '@metamask/tooling-insight';
+
+await run({ args: ['--dry-run'] });
+```
+
+## Environment variables
+
+The anonymizer reads push credentials from the environment, falling back to a `.js.env` file in the target repository root (shell-sourceable `export KEY="value"` format).
+
+| Variable                    | Description                                                                                                                                        |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MIMIR_URL`                 | Full URL of the Mimir remote-write endpoint (e.g. `https://mimir-dev.example.com/api/v1/push`).                                                    |
+| `MIMIR_USERNAME`            | HTTP Basic auth username. Required for authenticated endpoints (e.g. dev). Omit when access is network-controlled (e.g. prod via Cloudflare WARP). |
+| `MIMIR_PASSWORD`            | HTTP Basic auth password. Required for authenticated endpoints (e.g. dev). Omit when access is network-controlled (e.g. prod via Cloudflare WARP). |
+| `TOOL_USAGE_COLLECTION_DIR` | Override the directory where event logs and state are stored. Defaults to `~/.tool-usage-collection/`.                                             |
+| `METAMASK_SKILLS_DIR`       | Path to a checked-out copy of the MetaMask public skills repository (used to build the allowlist).                                                 |
+
+## API
+
+See our documentation:
+
+- [Latest published API documentation](https://metamask.github.io/experimental-tooling-insight/latest/)
+- [Latest development API documentation](https://metamask.github.io/experimental-tooling-insight/staging/)
+
+## Contributing
+
+### Setup
+
+- Install the current LTS version of [Node.js](https://nodejs.org)
+  - If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm install` will install the latest version and running `nvm use` will automatically choose the right node version for you.
+- Install [Yarn](https://yarnpkg.com) v4 via [Corepack](https://github.com/nodejs/corepack?tab=readme-ov-file#how-to-install)
+- Run `yarn install` to install dependencies and run any required post-install scripts
+
+### Testing and Linting
+
+Run `yarn test` to run the tests once. To run tests on file changes, run `yarn test:watch`.
+
+Run `yarn lint` to run the linter, or run `yarn lint:fix` to run the linter and fix any automatically fixable issues.
+
+### Release & Publishing
+
+The project follows the same release process as the other libraries in the MetaMask organization. The GitHub Actions [`action-create-release-pr`](https://github.com/MetaMask/action-create-release-pr) and [`action-publish-release`](https://github.com/MetaMask/action-publish-release) are used to automate the release process; see those repositories for more information about how they work.
+
+1. Choose a release version.
+
+2. Trigger the [`workflow_dispatch`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) event [manually](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow) for the `Create Release Pull Request` action to create the release PR.
+
+3. Update the changelog to move each change entry into the appropriate change category ([see here](https://keepachangelog.com/en/1.0.0/#types) for the full list of change categories), and edit them to be more easily understood by users of the package.
+
+4. Review and QA the release.
+
+5. Squash & Merge the release PR.
+
+6. Approve the `publish-npm` job (or ask somebody on the npm publishers team to approve it for you).
+
+### Testing changes in other projects using preview builds
+
+If you are working on a pull request and want to test changes in another project before publishing, you can create a _preview build_ and configure your project to use it.
+
+#### Creating a preview build
+
+1. Open the pull request you want to test.
+2. Post a comment with the exact text `@metamaskbot publish-preview`.
+3. The `publish-preview` workflow reacts to the comment with a +1, then runs and posts a follow-up comment containing the install identifier.
+
+Two things to note about preview builds:
+
+- The package name is scoped to `@metamask-previews` instead of `@metamask` (e.g. `@metamask-previews/tooling-insight`).
+- The short SHA of the last commit is appended to the version (e.g. `1.0.0-preview-e2df9b4` instead of `1.0.0`).
+
+Comments on PRs from forks are intentionally skipped — the token used to publish is never exposed to forked repositories.
+
+#### Using a preview build
+
+To use a preview build in a project, override the resolution logic so the production version is replaced by the preview version:
+
+1. Open `package.json` in the consuming project and find the entry for `@metamask/tooling-insight` in `dependencies`.
+2. Locate the resolution overrides section (create it if it doesn't exist). For Yarn this is `resolutions`; for npm it is `overrides`.
+3. Add an entry pointing to the preview version. Examples:
+
+   Yarn Modern (`resolutions`):
+
+   ```json
+   "@metamask/tooling-insight@^1.0.0": "npm:@metamask-previews/tooling-insight@1.0.0-preview-e2df9b4"
+   ```
+
+   Yarn Classic (`resolutions`):
+
+   ```json
+   "@metamask/tooling-insight": "npm:@metamask-previews/tooling-insight@1.0.0-preview-e2df9b4"
+   ```
+
+   npm (`overrides`):
+
+   ```json
+   "@metamask/tooling-insight": "npm:@metamask-previews/tooling-insight@1.0.0-preview-e2df9b4"
+   ```
+
+4. Run `yarn install`.
+
+#### Updating a preview build
+
+1. Post another `@metamaskbot publish-preview` comment on the pull request and wait for the follow-up comment with the new identifier.
+2. Update the pinned version in the consuming project's `package.json` and re-run `yarn install`.

package/dist/daily-anonymizer.cjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const run_1 = require("./run.cjs");
+(0, run_1.run)().catch(() => {
+    process.exitCode = 1;
+});
+//# sourceMappingURL=daily-anonymizer.cjs.map

package/dist/daily-anonymizer.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"daily-anonymizer.cjs","sourceRoot":"","sources":["../src/daily-anonymizer.ts"],"names":[],"mappings":";;;AACA,mCAA4B;AAE5B,IAAA,SAAG,GAAE,CAAC,KAAK,CAAC,GAAG,EAAE;IACf,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { run } from './run';\n\nrun().catch(() => {\n  process.exitCode = 1;\n});\n"]}

package/dist/daily-anonymizer.d.cts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=daily-anonymizer.d.cts.map

package/dist/daily-anonymizer.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daily-anonymizer.d.cts","sourceRoot":"","sources":["../src/daily-anonymizer.ts"],"names":[],"mappings":""}

package/dist/daily-anonymizer.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=daily-anonymizer.d.mts.map

package/dist/daily-anonymizer.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daily-anonymizer.d.mts","sourceRoot":"","sources":["../src/daily-anonymizer.ts"],"names":[],"mappings":""}

package/dist/daily-anonymizer.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { run } from "./run.mjs";
+run().catch(() => {
+    process.exitCode = 1;
+});
+//# sourceMappingURL=daily-anonymizer.mjs.map

package/dist/daily-anonymizer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"daily-anonymizer.mjs","sourceRoot":"","sources":["../src/daily-anonymizer.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,kBAAc;AAE5B,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;IACf,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { run } from './run';\n\nrun().catch(() => {\n  process.exitCode = 1;\n});\n"]}

package/dist/index.cjs

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = void 0;
+var run_1 = require("./run.cjs");
+Object.defineProperty(exports, "run", { enumerable: true, get: function () { return run_1.run; } });
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iCAA4B;AAAnB,0FAAA,GAAG,OAAA","sourcesContent":["export { run } from './run';\nexport type { RunOptions } from './run';\nexport type {\n  AnonymizerState,\n  Allowlist,\n  CsvEventType,\n  EventTypeLabel,\n  MetricName,\n  SampleLabels,\n  SamplePoint,\n  ToolEvent,\n  ToolType,\n} from './lib/types';\n"]}

package/dist/index.d.cts

@@ -0,0 +1,4 @@
+export { run } from "./run.cjs";
+export type { RunOptions } from "./run.cjs";
+export type { AnonymizerState, Allowlist, CsvEventType, EventTypeLabel, MetricName, SampleLabels, SamplePoint, ToolEvent, ToolType, } from "./lib/types.cjs";
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,kBAAc;AAC5B,YAAY,EAAE,UAAU,EAAE,kBAAc;AACxC,YAAY,EACV,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,UAAU,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,QAAQ,GACT,wBAAoB"}

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+export { run } from "./run.mjs";
+export type { RunOptions } from "./run.mjs";
+export type { AnonymizerState, Allowlist, CsvEventType, EventTypeLabel, MetricName, SampleLabels, SamplePoint, ToolEvent, ToolType, } from "./lib/types.mjs";
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,kBAAc;AAC5B,YAAY,EAAE,UAAU,EAAE,kBAAc;AACxC,YAAY,EACV,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,UAAU,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,QAAQ,GACT,wBAAoB"}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+export { run } from "./run.mjs";
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,kBAAc","sourcesContent":["export { run } from './run';\nexport type { RunOptions } from './run';\nexport type {\n  AnonymizerState,\n  Allowlist,\n  CsvEventType,\n  EventTypeLabel,\n  MetricName,\n  SampleLabels,\n  SamplePoint,\n  ToolEvent,\n  ToolType,\n} from './lib/types';\n"]}

package/dist/lib/allowlist.cjs

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findRepoRoot = findRepoRoot;
+exports.readAllowlist = readAllowlist;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ENV_METAMASK_SKILLS_DIR = 'METAMASK_SKILLS_DIR';
+const ENV_CONSENSYS_SKILLS_DIR = 'CONSENSYS_SKILLS_DIR';
+/**
+ * Thin wrapper around `execFileSync` used as the default git executor.
+ *
+ * @param file - The git executable path.
+ * @param args - Arguments to pass to git.
+ * @param options - Execution options including cwd and encoding.
+ * @param options.cwd - Optional working directory for the git command.
+ * @param options.encoding - Output encoding; must be `'utf8'`.
+ * @returns The stdout of the git command as a UTF-8 string.
+ */
+function defaultExecGit(file, args, options) {
+    return (0, node_child_process_1.execFileSync)(file, args, options);
+}
+/**
+ * Walk up from `startDir` until a directory containing `package.json` is found.
+ *
+ * @param startDir - Directory to start the search from.
+ * @returns The repo root directory, or `startDir` if no `package.json` is found.
+ */
+function findRepoRoot(startDir) {
+    let current = startDir;
+    while (true) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(current, 'package.json'))) {
+            return current;
+        }
+        const parent = (0, node_path_1.join)(current, '..');
+        if (parent === current) {
+            return startDir;
+        }
+        current = parent;
+    }
+}
+/**
+ * Parse the `.skills.local` key-value override file in the repo root.
+ *
+ * @param repoRoot - Absolute path to the repo root containing `.skills.local`.
+ * @returns A map of key-value pairs from the local skills override file.
+ */
+function parseSkillsLocal(repoRoot) {
+    const path = (0, node_path_1.join)(repoRoot, '.skills.local');
+    if (!(0, node_fs_1.existsSync)(path)) {
+        return {};
+    }
+    const entries = {};
+    for (const line of (0, node_fs_1.readFileSync)(path, 'utf8').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const eq = trimmed.indexOf('=');
+        if (eq === -1) {
+            continue;
+        }
+        entries[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+    }
+    return entries;
+}
+/**
+ * Resolve the absolute path for a skills directory from multiple sources in priority order:
+ * environment variable → `.skills.local` key → cached directory.
+ *
+ * @param envKey - Environment variable name to check first.
+ * @param skillsLocalKey - Key to look up in `.skills.local`.
+ * @param repoRoot - Repo root for `.skills.local` and fallback resolution.
+ * @param defaultRelative - Optional relative path to a cached skills directory under the repo root.
+ * @returns Absolute path to the skills directory, or `null` if unresolvable.
+ */
+function resolveSkillsDir(envKey, skillsLocalKey, repoRoot, defaultRelative) {
+    if (process.env[envKey]) {
+        return process.env[envKey];
+    }
+    const local = parseSkillsLocal(repoRoot)[skillsLocalKey];
+    if (local) {
+        return local;
+    }
+    if (defaultRelative) {
+        const cached = (0, node_path_1.join)(repoRoot, defaultRelative);
+        if ((0, node_fs_1.existsSync)(cached)) {
+            return cached;
+        }
+    }
+    return null;
+}
+/**
+ * Extract skill names from `git ls-tree` output by matching the `skill.md` path pattern.
+ *
+ * @param gitOutput - Raw `ls-tree` output from git.
+ * @returns An array of skill names prefixed with `mms-`.
+ */
+function extractSkillNames(gitOutput) {
+    const names = [];
+    for (const line of gitOutput.split('\n')) {
+        const match = line.match(/^domains\/[^/]+\/skills\/([^/]+)\/skill\.md$/u);
+        if (match) {
+            names.push(`mms-${match[1]}`);
+        }
+    }
+    return names;
+}
+/**
+ * List skill names by running `git ls-tree` against the skills git repository.
+ *
+ * @param dir - Absolute path to the skills git repository.
+ * @param execGit - Git executor function.
+ * @returns An array of skill names found in the skills repository.
+ */
+function readSkillsFromDir(dir, execGit) {
+    const output = execGit('git', ['-C', dir, 'ls-tree', '-r', '--name-only', 'main', '--', 'domains'], { encoding: 'utf8' });
+    return extractSkillNames(output);
+}
+/**
+ * Read yarn script names from the consuming repo's `main` branch `package.json`.
+ *
+ * @param repoRoot - Absolute path to the consuming repo root.
+ * @param execGit - Git executor function.
+ * @returns An array of yarn script names from the consuming repo's main branch.
+ */
+function readYarnScripts(repoRoot, execGit) {
+    const output = execGit('git', ['show', 'main:package.json'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+    });
+    const parsed = JSON.parse(output);
+    return Object.keys(parsed.scripts ?? {});
+}
+/**
+ * Read skill and yarn-script allowlists from local git refs.
+ * Private skills repo is optional; public skills + package.json scripts are required.
+ *
+ * @param options - Optional overrides for repo root and git executor.
+ * @returns The combined allowlist of skill names and yarn script names.
+ */
+function readAllowlist(options = {}) {
+    const repoRoot = options.repoRoot ?? findRepoRoot(process.cwd());
+    const execGit = options.execGit ?? defaultExecGit;
+    const publicDir = resolveSkillsDir(ENV_METAMASK_SKILLS_DIR, 'METAMASK_SKILLS_DIR', repoRoot, '.skills-cache/metamask-skills');
+    if (!publicDir) {
+        throw new Error('MetaMask skills source directory could not be resolved');
+    }
+    const privateDir = resolveSkillsDir(ENV_CONSENSYS_SKILLS_DIR, 'CONSENSYS_SKILLS_DIR', repoRoot);
+    const skills = new Set(readSkillsFromDir(publicDir, execGit));
+    if (privateDir) {
+        for (const name of readSkillsFromDir(privateDir, execGit)) {
+            skills.add(name);
+        }
+    }
+    const scripts = new Set(readYarnScripts(repoRoot, execGit));
+    return { skills, scripts };
+}
+//# sourceMappingURL=allowlist.cjs.map

package/dist/lib/allowlist.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.cjs","sourceRoot":"","sources":["../../src/lib/allowlist.ts"],"names":[],"mappings":"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","sourcesContent":["import { execFileSync } from 'node:child_process';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\nimport type { Allowlist } from './types';\n\nconst ENV_METAMASK_SKILLS_DIR = 'METAMASK_SKILLS_DIR';\nconst ENV_CONSENSYS_SKILLS_DIR = 'CONSENSYS_SKILLS_DIR';\n\n/** Signature of the git executor passed to allowlist readers, matching `execFileSync`. */\nexport type ExecGit = (\n  file: string,\n  args: readonly string[],\n  options: {\n    /** Optional working directory for the git command. */\n    cwd?: string;\n    /** Output encoding; must be `'utf8'`. */\n    encoding: 'utf8';\n  },\n) => string;\n\n/** Options for `readAllowlist`. */\nexport type AllowlistOptions = {\n  /** Absolute path to the repo root; defaults to `findRepoRoot(process.cwd())`. */\n  repoRoot?: string;\n  /** Git executor; defaults to the real `execFileSync` wrapper. */\n  execGit?: ExecGit;\n};\n\n/**\n * Thin wrapper around `execFileSync` used as the default git executor.\n *\n * @param file - The git executable path.\n * @param args - Arguments to pass to git.\n * @param options - Execution options including cwd and encoding.\n * @param options.cwd - Optional working directory for the git command.\n * @param options.encoding - Output encoding; must be `'utf8'`.\n * @returns The stdout of the git command as a UTF-8 string.\n */\nfunction defaultExecGit(\n  file: string,\n  args: readonly string[],\n  options: {\n    /** Optional working directory for the git command. */\n    cwd?: string;\n    /** Output encoding; must be `'utf8'`. */\n    encoding: 'utf8';\n  },\n): string {\n  return execFileSync(file, args, options);\n}\n\n/**\n * Walk up from `startDir` until a directory containing `package.json` is found.\n *\n * @param startDir - Directory to start the search from.\n * @returns The repo root directory, or `startDir` if no `package.json` is found.\n */\nexport function findRepoRoot(startDir: string): string {\n  let current = startDir;\n  while (true) {\n    if (existsSync(join(current, 'package.json'))) {\n      return current;\n    }\n    const parent = join(current, '..');\n    if (parent === current) {\n      return startDir;\n    }\n    current = parent;\n  }\n}\n\n/**\n * Parse the `.skills.local` key-value override file in the repo root.\n *\n * @param repoRoot - Absolute path to the repo root containing `.skills.local`.\n * @returns A map of key-value pairs from the local skills override file.\n */\nfunction parseSkillsLocal(repoRoot: string): Record<string, string> {\n  const path = join(repoRoot, '.skills.local');\n  if (!existsSync(path)) {\n    return {};\n  }\n  const entries: Record<string, string> = {};\n  for (const line of readFileSync(path, 'utf8').split('\\n')) {\n    const trimmed = line.trim();\n    if (!trimmed || trimmed.startsWith('#')) {\n      continue;\n    }\n    const eq = trimmed.indexOf('=');\n    if (eq === -1) {\n      continue;\n    }\n    entries[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();\n  }\n  return entries;\n}\n\n/**\n * Resolve the absolute path for a skills directory from multiple sources in priority order:\n * environment variable → `.skills.local` key → cached directory.\n *\n * @param envKey - Environment variable name to check first.\n * @param skillsLocalKey - Key to look up in `.skills.local`.\n * @param repoRoot - Repo root for `.skills.local` and fallback resolution.\n * @param defaultRelative - Optional relative path to a cached skills directory under the repo root.\n * @returns Absolute path to the skills directory, or `null` if unresolvable.\n */\nfunction resolveSkillsDir(\n  envKey: string,\n  skillsLocalKey: string,\n  repoRoot: string,\n  defaultRelative?: string,\n): string | null {\n  if (process.env[envKey]) {\n    return process.env[envKey];\n  }\n  const local = parseSkillsLocal(repoRoot)[skillsLocalKey];\n  if (local) {\n    return local;\n  }\n  if (defaultRelative) {\n    const cached = join(repoRoot, defaultRelative);\n    if (existsSync(cached)) {\n      return cached;\n    }\n  }\n  return null;\n}\n\n/**\n * Extract skill names from `git ls-tree` output by matching the `skill.md` path pattern.\n *\n * @param gitOutput - Raw `ls-tree` output from git.\n * @returns An array of skill names prefixed with `mms-`.\n */\nfunction extractSkillNames(gitOutput: string): string[] {\n  const names: string[] = [];\n  for (const line of gitOutput.split('\\n')) {\n    const match = line.match(/^domains\\/[^/]+\\/skills\\/([^/]+)\\/skill\\.md$/u);\n    if (match) {\n      names.push(`mms-${match[1]}`);\n    }\n  }\n  return names;\n}\n\n/**\n * List skill names by running `git ls-tree` against the skills git repository.\n *\n * @param dir - Absolute path to the skills git repository.\n * @param execGit - Git executor function.\n * @returns An array of skill names found in the skills repository.\n */\nfunction readSkillsFromDir(dir: string, execGit: ExecGit): string[] {\n  const output = execGit(\n    'git',\n    ['-C', dir, 'ls-tree', '-r', '--name-only', 'main', '--', 'domains'],\n    { encoding: 'utf8' },\n  );\n  return extractSkillNames(output);\n}\n\n/**\n * Read yarn script names from the consuming repo's `main` branch `package.json`.\n *\n * @param repoRoot - Absolute path to the consuming repo root.\n * @param execGit - Git executor function.\n * @returns An array of yarn script names from the consuming repo's main branch.\n */\nfunction readYarnScripts(repoRoot: string, execGit: ExecGit): string[] {\n  const output = execGit('git', ['show', 'main:package.json'], {\n    cwd: repoRoot,\n    encoding: 'utf8',\n  });\n  const parsed = JSON.parse(output) as {\n    /** Map of yarn script names to their shell commands. */\n    scripts?: Record<string, string>;\n  };\n  return Object.keys(parsed.scripts ?? {});\n}\n\n/**\n * Read skill and yarn-script allowlists from local git refs.\n * Private skills repo is optional; public skills + package.json scripts are required.\n *\n * @param options - Optional overrides for repo root and git executor.\n * @returns The combined allowlist of skill names and yarn script names.\n */\nexport function readAllowlist(options: AllowlistOptions = {}): Allowlist {\n  const repoRoot = options.repoRoot ?? findRepoRoot(process.cwd());\n  const execGit = options.execGit ?? defaultExecGit;\n\n  const publicDir = resolveSkillsDir(\n    ENV_METAMASK_SKILLS_DIR,\n    'METAMASK_SKILLS_DIR',\n    repoRoot,\n    '.skills-cache/metamask-skills',\n  );\n  if (!publicDir) {\n    throw new Error('MetaMask skills source directory could not be resolved');\n  }\n\n  const privateDir = resolveSkillsDir(\n    ENV_CONSENSYS_SKILLS_DIR,\n    'CONSENSYS_SKILLS_DIR',\n    repoRoot,\n  );\n\n  const skills = new Set<string>(readSkillsFromDir(publicDir, execGit));\n  if (privateDir) {\n    for (const name of readSkillsFromDir(privateDir, execGit)) {\n      skills.add(name);\n    }\n  }\n\n  const scripts = new Set<string>(readYarnScripts(repoRoot, execGit));\n\n  return { skills, scripts };\n}\n"]}

package/dist/lib/allowlist.d.cts

@@ -0,0 +1,31 @@
+import type { Allowlist } from "./types.cjs";
+/** Signature of the git executor passed to allowlist readers, matching `execFileSync`. */
+export type ExecGit = (file: string, args: readonly string[], options: {
+    /** Optional working directory for the git command. */
+    cwd?: string;
+    /** Output encoding; must be `'utf8'`. */
+    encoding: 'utf8';
+}) => string;
+/** Options for `readAllowlist`. */
+export type AllowlistOptions = {
+    /** Absolute path to the repo root; defaults to `findRepoRoot(process.cwd())`. */
+    repoRoot?: string;
+    /** Git executor; defaults to the real `execFileSync` wrapper. */
+    execGit?: ExecGit;
+};
+/**
+ * Walk up from `startDir` until a directory containing `package.json` is found.
+ *
+ * @param startDir - Directory to start the search from.
+ * @returns The repo root directory, or `startDir` if no `package.json` is found.
+ */
+export declare function findRepoRoot(startDir: string): string;
+/**
+ * Read skill and yarn-script allowlists from local git refs.
+ * Private skills repo is optional; public skills + package.json scripts are required.
+ *
+ * @param options - Optional overrides for repo root and git executor.
+ * @returns The combined allowlist of skill names and yarn script names.
+ */
+export declare function readAllowlist(options?: AllowlistOptions): Allowlist;
+//# sourceMappingURL=allowlist.d.cts.map

package/dist/lib/allowlist.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.d.cts","sourceRoot":"","sources":["../../src/lib/allowlist.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAgB;AAKzC,0FAA0F;AAC1F,MAAM,MAAM,OAAO,GAAG,CACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;CAClB,KACE,MAAM,CAAC;AAEZ,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAyBF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYrD;AAgHD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS,CA8BvE"}

package/dist/lib/allowlist.d.mts

@@ -0,0 +1,31 @@
+import type { Allowlist } from "./types.mjs";
+/** Signature of the git executor passed to allowlist readers, matching `execFileSync`. */
+export type ExecGit = (file: string, args: readonly string[], options: {
+    /** Optional working directory for the git command. */
+    cwd?: string;
+    /** Output encoding; must be `'utf8'`. */
+    encoding: 'utf8';
+}) => string;
+/** Options for `readAllowlist`. */
+export type AllowlistOptions = {
+    /** Absolute path to the repo root; defaults to `findRepoRoot(process.cwd())`. */
+    repoRoot?: string;
+    /** Git executor; defaults to the real `execFileSync` wrapper. */
+    execGit?: ExecGit;
+};
+/**
+ * Walk up from `startDir` until a directory containing `package.json` is found.
+ *
+ * @param startDir - Directory to start the search from.
+ * @returns The repo root directory, or `startDir` if no `package.json` is found.
+ */
+export declare function findRepoRoot(startDir: string): string;
+/**
+ * Read skill and yarn-script allowlists from local git refs.
+ * Private skills repo is optional; public skills + package.json scripts are required.
+ *
+ * @param options - Optional overrides for repo root and git executor.
+ * @returns The combined allowlist of skill names and yarn script names.
+ */
+export declare function readAllowlist(options?: AllowlistOptions): Allowlist;
+//# sourceMappingURL=allowlist.d.mts.map

package/dist/lib/allowlist.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.d.mts","sourceRoot":"","sources":["../../src/lib/allowlist.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAgB;AAKzC,0FAA0F;AAC1F,MAAM,MAAM,OAAO,GAAG,CACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;CAClB,KACE,MAAM,CAAC;AAEZ,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAyBF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYrD;AAgHD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS,CA8BvE"}