@adguard/agtree 1.1.4 → 1.1.5

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog][keepachangelog], and this project adheres to [Semantic Versioning][semver].
 
+
+## 1.1.5 - 2023-09-05
+
+### Changed
+
+- Validation of `$csp` and `$permissions` modifiers value
+  by custom pre-defined validator instead of regular expression
+
+### Added
+
+- Exports to `package.json`
+
 ## 1.1.4 - 2023-08-30
 
 ### Fixed

package/dist/agtree.cjs

@@ -1,5 +1,5 @@
 /*
- * AGTree v1.1.4 (build date: Wed, 30 Aug 2023 10:02:46 GMT)
+ * AGTree v1.1.5 (build date: Tue, 05 Sep 2023 15:10:53 GMT)
  * (c) 2023 AdGuard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
@@ -88,6 +88,9 @@ exports.AdblockSyntax = void 0;
  * @file Constant values used by all parts of the library
  */
 // General
+/**
+ * Empty string.
+ */
 const EMPTY = '';
 const SPACE = ' ';
 const TAB = '\t';
@@ -6144,7 +6147,7 @@ var data$N = { adg_os_any:{ name:"csp",
     assignable:true,
     negatable:false,
     value_optional:true,
-    value_format:"(?xi)\n  ^(\n    base-uri|\n    child-src|\n    connect-src|\n    default-src|\n    font-src|\n    form-action|\n    frame-ancestors|\n    frame-src|\n    img-src|\n    manifest-src|\n    media-src|\n    navigate-to|\n    object-src|\n    plugin-types|\n    prefetch-src|\n    report-to|\n    report-uri|\n    sandbox|\n    script-src|\n    style-src|\n    upgrade-insecure-requests|\n    worker-src|\n  )\n  \\s+\n  \\S{1,}" },
+    value_format:"csp_value" },
   adg_ext_any:{ name:"csp",
     description:"This modifier completely changes the rule behavior.\nIf it is applied to a rule, it will not block the matching request.\nThe response headers are going to be modified instead.",
     docs:"https://adguard.app/kb/general/ad-filtering/create-own-filters/#csp-modifier",
@@ -6156,7 +6159,7 @@ var data$N = { adg_os_any:{ name:"csp",
     assignable:true,
     negatable:false,
     value_optional:true,
-    value_format:"(?xi)\n  ^(\n    base-uri|\n    child-src|\n    connect-src|\n    default-src|\n    font-src|\n    form-action|\n    frame-ancestors|\n    frame-src|\n    img-src|\n    manifest-src|\n    media-src|\n    navigate-to|\n    object-src|\n    plugin-types|\n    prefetch-src|\n    report-to|\n    report-uri|\n    sandbox|\n    script-src|\n    style-src|\n    upgrade-insecure-requests|\n    worker-src|\n  )\n  \\s+\n  \\S{1,}" },
+    value_format:"csp_value" },
   abp_ext_any:{ name:"csp",
     description:"This modifier completely changes the rule behavior.\nIf it is applied to a rule, it will not block the matching request.\nThe response headers are going to be modified instead.",
     docs:"https://help.adblockplus.org/hc/en-us/articles/360062733293-How-to-write-filters#content-security-policies",
@@ -6166,7 +6169,7 @@ var data$N = { adg_os_any:{ name:"csp",
     assignable:true,
     negatable:false,
     value_optional:true,
-    value_format:"(?xi)\n  ^(\n    base-uri|\n    child-src|\n    connect-src|\n    default-src|\n    font-src|\n    form-action|\n    frame-ancestors|\n    frame-src|\n    img-src|\n    manifest-src|\n    media-src|\n    navigate-to|\n    object-src|\n    plugin-types|\n    prefetch-src|\n    report-to|\n    report-uri|\n    sandbox|\n    script-src|\n    style-src|\n    upgrade-insecure-requests|\n    worker-src|\n  )\n  \\s+\n  \\S{1,}" },
+    value_format:"csp_value" },
   ubo_ext_any:{ name:"csp",
     description:"This modifier completely changes the rule behavior.\nIf it is applied to a rule, it will not block the matching request.\nThe response headers are going to be modified instead.",
     docs:"https://github.com/gorhill/uBlock/wiki/Static-filter-syntax#csp",
@@ -6178,7 +6181,7 @@ var data$N = { adg_os_any:{ name:"csp",
     assignable:true,
     negatable:false,
     value_optional:true,
-    value_format:"(?xi)\n  ^(\n    base-uri|\n    child-src|\n    connect-src|\n    default-src|\n    font-src|\n    form-action|\n    frame-ancestors|\n    frame-src|\n    img-src|\n    manifest-src|\n    media-src|\n    navigate-to|\n    object-src|\n    plugin-types|\n    prefetch-src|\n    report-to|\n    report-uri|\n    sandbox|\n    script-src|\n    style-src|\n    upgrade-insecure-requests|\n    worker-src|\n  )\n  \\s+\n  \\S{1,}" } };
+    value_format:"csp_value" } };
 
 var data$M = { adg_os_any:{ name:"denyallow",
     description:"The `$denyallow` modifier allows to avoid creating additional rules\nwhen it is needed to disable a certain rule for specific domains.\n`$denyallow` matches only target domains and not referrer domains.",
@@ -6685,7 +6688,8 @@ var data$l = { adg_os_any:{ name:"permissions",
     inverse_conflicts:true,
     assignable:true,
     negatable:false,
-    value_format:"(?x)\n  ^\n    (\n      ?:(\n        accelerometer|\n        ambient-light-sensor|\n        autoplay|\n        battery|\n        camera|\n        display-capture|\n        document-domain|\n        encrypted-media|\n        execution-while-not-rendered|\n        execution-while-out-of-viewport|\n        fullscreen|\n        gamepad|\n        geolocation|\n        gyroscope|\n        hid|\n        identity-credentials-get|\n        idle-detection|\n        local-fonts|\n        magnetometer|\n        microphone|\n        midi|\n        payment|\n        picture-in-picture|\n        publickey-credentials-create|\n        publickey-credentials-get|\n        screen-wake-lock|\n        serial|\n        speaker-selection|\n        storage-access|\n        usb|\n        web-share|\n        xr-spatial-tracking\n      )\n      =\\(\\)\n      # optional escaped comma for multiple permissions\n      (\\\\,(\\s+)?)?\n    )+\n  $" } };
+    value_optional:true,
+    value_format:"permissions_value" } };
 
 var data$k = { adg_any:{ name:"ping",
     description:"The rule corresponds to requests caused by either navigator.sendBeacon() or the ping attribute on links.",
@@ -7346,15 +7350,104 @@ const ALLOWED_STEALTH_OPTIONS = new Set([
     'xclientdata',
     'dpi',
 ]);
+/**
+ * Allowed CSP directives for $csp modifier.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives}
+ */
+const ALLOWED_CSP_DIRECTIVES = new Set([
+    'base-uri',
+    'child-src',
+    'connect-src',
+    'default-src',
+    'font-src',
+    'form-action',
+    'frame-ancestors',
+    'frame-src',
+    'img-src',
+    'manifest-src',
+    'media-src',
+    'navigate-to',
+    'object-src',
+    'plugin-types',
+    'prefetch-src',
+    'report-to',
+    'report-uri',
+    'sandbox',
+    'script-src',
+    'style-src',
+    'upgrade-insecure-requests',
+    'worker-src',
+]);
+/**
+ * Allowed stealth options for $permissions modifier.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#permissions-modifier}
+ */
+const ALLOWED_PERMISSION_DIRECTIVES = new Set([
+    'accelerometer',
+    'ambient-light-sensor',
+    'autoplay',
+    'battery',
+    'camera',
+    'display-capture',
+    'document-domain',
+    'encrypted-media',
+    'execution-while-not-rendered',
+    'execution-while-out-of-viewport',
+    'fullscreen',
+    'gamepad',
+    'geolocation',
+    'gyroscope',
+    'hid',
+    'identity-credentials-get',
+    'idle-detection',
+    'local-fonts',
+    'magnetometer',
+    'microphone',
+    'midi',
+    'payment',
+    'picture-in-picture',
+    'publickey-credentials-create',
+    'publickey-credentials-get',
+    'screen-wake-lock',
+    'serial',
+    'speaker-selection',
+    'storage-access',
+    'usb',
+    'web-share',
+    'xr-spatial-tracking',
+]);
+/**
+ * One of available tokens for $permission modifier value.
+ *
+ * @see {@link https://w3c.github.io/webappsec-permissions-policy/#structured-header-serialization}
+ */
+const PERMISSIONS_TOKEN_SELF = 'self';
+/**
+ * One of allowlist values for $permissions modifier.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Permissions_Policy#allowlists}
+ */
+const EMPTY_PERMISSIONS_ALLOWLIST = `${OPEN_PARENTHESIS}${CLOSE_PARENTHESIS}`;
 /**
  * Prefixes for error messages used in modifier validation.
  */
 const VALIDATION_ERROR_PREFIX = {
     BLOCK_ONLY: 'Only blocking rules may contain the modifier',
     EXCEPTION_ONLY: 'Only exception rules may contain the modifier',
+    INVALID_CSP_DIRECTIVES: 'Invalid CSP directives for the modifier',
     INVALID_LIST_VALUES: 'Invalid values for the modifier',
     INVALID_NOOP: 'Invalid noop modifier',
+    INVALID_PERMISSION_DIRECTIVE: 'Invalid Permissions-Policy directive for the modifier',
+    INVALID_PERMISSION_ORIGINS: 'Origins in the value is invalid for the modifier and the directive',
+    INVALID_PERMISSION_ORIGIN_QUOTES: 'Double quotes should be used for origins in the value of the modifier',
     MIXED_NEGATIONS: 'Simultaneous usage of negated and not negated values is forbidden for the modifier',
+    NO_CSP_VALUE: 'No CSP value for the modifier and the directive',
+    NO_CSP_DIRECTIVE_QUOTE: 'CSP directives should no be quoted for the modifier',
+    NO_UNESCAPED_PERMISSION_COMMA: 'Unescaped comma in the value is not allowed for the modifier',
+    // TODO: implement later for $scp and $permissions
+    // NO_VALUE_ONLY_FOR_EXCEPTION: 'Modifier without value can be used only in exception rules',
     NOT_EXISTENT: 'Non-existent modifier',
     NOT_NEGATABLE_MODIFIER: 'Non-negatable modifier',
     NOT_NEGATABLE_VALUE: 'Values cannot be negated for the modifier',
@@ -7666,10 +7759,12 @@ class QuoteUtils {
 var CustomValueFormatValidatorName;
 (function (CustomValueFormatValidatorName) {
     CustomValueFormatValidatorName["App"] = "pipe_separated_apps";
+    CustomValueFormatValidatorName["Csp"] = "csp_value";
     // there are some differences between $domain and $denyallow
     CustomValueFormatValidatorName["DenyAllow"] = "pipe_separated_denyallow_domains";
     CustomValueFormatValidatorName["Domain"] = "pipe_separated_domains";
     CustomValueFormatValidatorName["Method"] = "pipe_separated_methods";
+    CustomValueFormatValidatorName["Permissions"] = "permissions_value";
     CustomValueFormatValidatorName["StealthOption"] = "pipe_separated_stealth_options";
 })(CustomValueFormatValidatorName || (CustomValueFormatValidatorName = {}));
 /**
@@ -7730,6 +7825,32 @@ const isValidMethodModifierValue = (value) => {
 const isValidStealthModifierValue = (value) => {
     return ALLOWED_STEALTH_OPTIONS.has(value);
 };
+/**
+ * Checks whether the given `rawOrigin` is valid as Permissions Allowlist origin.
+ *
+ * @see {@link https://w3c.github.io/webappsec-permissions-policy/#allowlists}
+ *
+ * @param rawOrigin The raw origin.
+ *
+ * @returns True if the origin is valid, false otherwise.
+ */
+const isValidPermissionsOrigin = (rawOrigin) => {
+    // origins should be quoted by double quote
+    const actualQuoteType = QuoteUtils.getStringQuoteType(rawOrigin);
+    if (actualQuoteType !== exports.QuoteType.Double) {
+        return false;
+    }
+    const origin = QuoteUtils.removeQuotes(rawOrigin);
+    try {
+        // validate the origin by URL constructor
+        // https://w3c.github.io/webappsec-permissions-policy/#algo-parse-policy-directive
+        new URL(origin);
+    }
+    catch (e) {
+        return false;
+    }
+    return true;
+};
 /**
  * Checks whether the given `value` is valid domain as $denyallow modifier value.
  * Important: wildcard tld are not supported, compared to $domain.
@@ -7920,14 +8041,196 @@ const validatePipeSeparatedMethods = (modifier) => {
 const validatePipeSeparatedStealthOptions = (modifier) => {
     return validateListItemsModifier(modifier, (raw) => StealthOptionListParser.parse(raw), isValidStealthModifierValue, customNoNegatedListItemsValidator);
 };
+/**
+ * Validates `csp_value` custom value format.
+ * Used for $csp modifier.
+ *
+ * @param modifier Modifier AST node.
+ *
+ * @returns Validation result.
+ */
+const validateCspValue = (modifier) => {
+    const modifierName = modifier.modifier.value;
+    if (!modifier.value?.value) {
+        return getValueRequiredValidationResult(modifierName);
+    }
+    // $csp modifier value may contain multiple directives
+    // e.g. "csp=child-src 'none'; frame-src 'self' *; worker-src 'none'"
+    const policyDirectives = modifier.value.value
+        .split(SEMICOLON)
+        // rule with $csp modifier may end with semicolon
+        // e.g. "$csp=sandbox allow-same-origin;"
+        // TODO: add predicate helper for `(i) => !!i`
+        .filter((i) => !!i);
+    const invalidValueValidationResult = getInvalidValidationResult(`${VALIDATION_ERROR_PREFIX.VALUE_INVALID}: '${modifierName}': "${modifier.value.value}"`);
+    if (policyDirectives.length === 0) {
+        return invalidValueValidationResult;
+    }
+    const invalidDirectives = [];
+    for (let i = 0; i < policyDirectives.length; i += 1) {
+        const policyDirective = policyDirectives[i].trim();
+        if (!policyDirective) {
+            return invalidValueValidationResult;
+        }
+        const chunks = policyDirective.split(SPACE);
+        const [directive, ...valueChunks] = chunks;
+        // e.g. "csp=child-src 'none'; ; worker-src 'none'"
+        // validator it here          ↑
+        if (!directive) {
+            return invalidValueValidationResult;
+        }
+        if (!ALLOWED_CSP_DIRECTIVES.has(directive)) {
+            // e.g. "csp='child-src' 'none'"
+            if (ALLOWED_CSP_DIRECTIVES.has(QuoteUtils.removeQuotes(directive))) {
+                return getInvalidValidationResult(`${VALIDATION_ERROR_PREFIX.NO_CSP_DIRECTIVE_QUOTE}: '${modifierName}': ${directive}`);
+            }
+            invalidDirectives.push(directive);
+            continue;
+        }
+        if (valueChunks.length === 0) {
+            return getInvalidValidationResult(`${VALIDATION_ERROR_PREFIX.NO_CSP_VALUE}: '${modifierName}': '${directive}'`);
+        }
+    }
+    if (invalidDirectives.length > 0) {
+        const directivesToStr = QuoteUtils.quoteAndJoinStrings(invalidDirectives, exports.QuoteType.Double);
+        return getInvalidValidationResult(`${VALIDATION_ERROR_PREFIX.INVALID_CSP_DIRECTIVES}: '${modifierName}': ${directivesToStr}`);
+    }
+    return { valid: true };
+};
+/**
+ * Validates permission allowlist origins in the value of $permissions modifier.
+ *
+ * @see {@link https://w3c.github.io/webappsec-permissions-policy/#allowlists}
+ *
+ * @param allowlistChunks Array of allowlist chunks.
+ * @param directive Permission directive name.
+ * @param modifierName Modifier name.
+ *
+ * @returns Validation result.
+ */
+const validatePermissionAllowlistOrigins = (allowlistChunks, directive, modifierName) => {
+    const invalidOrigins = [];
+    for (let i = 0; i < allowlistChunks.length; i += 1) {
+        const chunk = allowlistChunks[i].trim();
+        // skip few spaces between origins (they were splitted by space)
+        // e.g. 'geolocation=("https://example.com"  "https://*.example.com")'
+        if (chunk.length === 0) {
+            continue;
+        }
+        /**
+         * 'self' should be checked case-insensitively
+         *
+         * @see {@link https://w3c.github.io/webappsec-permissions-policy/#algo-parse-policy-directive}
+         *
+         * @example 'geolocation=(self)'
+         */
+        if (chunk.toLowerCase() === PERMISSIONS_TOKEN_SELF) {
+            continue;
+        }
+        if (QuoteUtils.getStringQuoteType(chunk) !== exports.QuoteType.Double) {
+            return getInvalidValidationResult(
+            // eslint-disable-next-line max-len
+            `${VALIDATION_ERROR_PREFIX.INVALID_PERMISSION_ORIGIN_QUOTES}: '${modifierName}': '${directive}': '${QuoteUtils.removeQuotes(chunk)}'`);
+        }
+        if (!isValidPermissionsOrigin(chunk)) {
+            invalidOrigins.push(chunk);
+        }
+    }
+    if (invalidOrigins.length > 0) {
+        const originsToStr = QuoteUtils.quoteAndJoinStrings(invalidOrigins);
+        return getInvalidValidationResult(
+        // eslint-disable-next-line max-len
+        `${VALIDATION_ERROR_PREFIX.INVALID_PERMISSION_ORIGINS}: '${modifierName}': '${directive}': ${originsToStr}`);
+    }
+    return { valid: true };
+};
+/**
+ * Validates permission allowlist in the modifier value.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Permissions_Policy#allowlists}
+ * @see {@link https://w3c.github.io/webappsec-permissions-policy/#allowlists}
+ *
+ * @param allowlist Allowlist value.
+ * @param directive Permission directive name.
+ * @param modifierName Modifier name.
+ *
+ * @returns Validation result.
+ */
+const validatePermissionAllowlist = (allowlist, directive, modifierName) => {
+    // `*` is one of available permissions tokens
+    // e.g. 'fullscreen=*'
+    // https://w3c.github.io/webappsec-permissions-policy/#structured-header-serialization
+    if (allowlist === WILDCARD$1
+        // e.g. 'autoplay=()'
+        || allowlist === EMPTY_PERMISSIONS_ALLOWLIST) {
+        return { valid: true };
+    }
+    if (!(allowlist.startsWith(OPEN_PARENTHESIS) && allowlist.endsWith(CLOSE_PARENTHESIS))) {
+        return getInvalidValidationResult(`${VALIDATION_ERROR_PREFIX.VALUE_INVALID}: '${modifierName}'`);
+    }
+    const allowlistChunks = allowlist.slice(1, -1).split(SPACE);
+    return validatePermissionAllowlistOrigins(allowlistChunks, directive, modifierName);
+};
+/**
+ * Validates single permission in the modifier value.
+ *
+ * @param permission Single permission value.
+ * @param modifierName Modifier name.
+ * @param modifierValue Modifier value.
+ *
+ * @returns Validation result.
+ */
+const validateSinglePermission = (permission, modifierName, modifierValue) => {
+    // empty permission in the rule
+    // e.g. 'permissions=storage-access=()\\, \\, camera=()'
+    // the validator is here                 ↑
+    if (!permission) {
+        return getInvalidValidationResult(`${VALIDATION_ERROR_PREFIX.VALUE_INVALID}: '${modifierName}'`);
+    }
+    if (permission.includes(COMMA)) {
+        return getInvalidValidationResult(`${VALIDATION_ERROR_PREFIX.NO_UNESCAPED_PERMISSION_COMMA}: '${modifierName}': '${modifierValue}'`);
+    }
+    const [directive, allowlist] = permission.split(EQUALS);
+    if (!ALLOWED_PERMISSION_DIRECTIVES.has(directive)) {
+        return getInvalidValidationResult(`${VALIDATION_ERROR_PREFIX.INVALID_PERMISSION_DIRECTIVE}: '${modifierName}': '${directive}'`);
+    }
+    return validatePermissionAllowlist(allowlist, directive, modifierName);
+};
+/**
+ * Validates `permissions_value` custom value format.
+ * Used for $permissions modifier.
+ *
+ * @param modifier Modifier AST node.
+ *
+ * @returns Validation result.
+ */
+const validatePermissions = (modifier) => {
+    if (!modifier.value?.value) {
+        return getValueRequiredValidationResult(modifier.modifier.value);
+    }
+    const modifierName = modifier.modifier.value;
+    const modifierValue = modifier.value.value;
+    // multiple permissions may be separated by escaped commas
+    const permissions = modifier.value.value.split(`${BACKSLASH}${COMMA}`);
+    for (let i = 0; i < permissions.length; i += 1) {
+        const permission = permissions[i].trim();
+        const singlePermissionValidationResult = validateSinglePermission(permission, modifierName, modifierValue);
+        if (!singlePermissionValidationResult.valid) {
+            return singlePermissionValidationResult;
+        }
+    }
+    return { valid: true };
+};
 /**
  * Map of all available pre-defined validators for modifiers with custom `value_format`.
  */
 const CUSTOM_VALUE_FORMAT_MAP = {
     [CustomValueFormatValidatorName.App]: validatePipeSeparatedApps,
+    [CustomValueFormatValidatorName.Csp]: validateCspValue,
     [CustomValueFormatValidatorName.DenyAllow]: validatePipeSeparatedDenyAllowDomains,
     [CustomValueFormatValidatorName.Domain]: validatePipeSeparatedDomains,
     [CustomValueFormatValidatorName.Method]: validatePipeSeparatedMethods,
+    [CustomValueFormatValidatorName.Permissions]: validatePermissions,
     [CustomValueFormatValidatorName.StealthOption]: validatePipeSeparatedStealthOptions,
 };
 /**
@@ -8030,6 +8333,10 @@ const validateForSpecificSyntax = (modifiersData, syntax, modifier, isException)
     // e.g. 'domain'
     if (specificBlockerData[SpecificKey.Assignable]) {
         if (!modifier.value) {
+            // TODO: ditch value_optional after custom validators are implemented for value_format for all modifiers.
+            // This checking should be done in each separate custom validator,
+            // because $csp and $permissions without value can be used only in extension rules,
+            // but $cookie with no value can be used in both blocking and exception rules.
             /**
              * Some assignable modifiers can be used without a value,
              * e.g. '@@||example.com^$cookie'.
@@ -9279,6 +9586,11 @@ class CosmeticRuleConverter extends RuleConverterBase {
 /**
  * @file Network rule modifier list converter.
  */
+// Since scriptlets library doesn't have ESM exports, we should import
+// the whole module and then extract the required functions from it here.
+// Otherwise importing AGTree will cause an error in ESM environment,
+// because scriptlets library doesn't support named exports.
+const { redirects } = scriptlets;
 /**
  * @see {@link https://adguard.com/kb/general/ad-filtering/create-own-filters/#csp-modifier}
  */
@@ -9394,7 +9706,7 @@ class NetworkRuleModifierListConverter extends ConverterBase {
                     : modifierNode.modifier.value;
                 // Try to convert the redirect resource name to ADG format
                 // This function returns undefined if the resource name is unknown
-                const convertedRedirectResource = scriptlets.redirects.convertRedirectNameToAdg(redirectResource);
+                const convertedRedirectResource = redirects.convertRedirectNameToAdg(redirectResource);
                 convertedModifierList.children.push(createModifierNode(modifierName, 
                 // If the redirect resource name is unknown, fall back to the original one
                 // Later, the validator will throw an error if the resource name is invalid
@@ -9615,7 +9927,7 @@ class LogicalExpressionUtils {
     }
 }
 
-const version$1 = "1.1.4";
+const version$1 = "1.1.5";
 
 /**
  * @file AGTree version

package/dist/agtree.d.ts

@@ -1,5 +1,5 @@
 /*
- * AGTree v1.1.4 (build date: Wed, 30 Aug 2023 10:02:46 GMT)
+ * AGTree v1.1.5 (build date: Tue, 05 Sep 2023 15:10:53 GMT)
  * (c) 2023 AdGuard Software Ltd.
  * Released under the MIT license
  * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme