ssh-config 5.0.3 → 5.1.0

package/Readme.md

@@ -2,7 +2,9 @@
 
 [![NPM Downloads](https://img.shields.io/npm/dm/ssh-config.svg?style=flat)](https://www.npmjs.com/package/ssh-config)
 [![NPM Version](http://img.shields.io/npm/v/ssh-config.svg?style=flat)](https://www.npmjs.com/package/ssh-config)
+![JSR Version](https://img.shields.io/jsr/v/%40cyjake/ssh-config)
 [![Build Status](https://travis-ci.org/cyjake/ssh-config.svg)](https://travis-ci.org/cyjake/ssh-config)
+[![Deno CI](https://github.com/cyjake/ssh-config/actions/workflows/deno.yml/badge.svg)](https://github.com/cyjake/ssh-config/actions/workflows/deno.yml)
 [![Node CI](https://github.com/cyjake/ssh-config/actions/workflows/nodejs.yml/badge.svg)](https://github.com/cyjake/ssh-config/actions/workflows/nodejs.yml)
 [![codecov](https://codecov.io/gh/cyjake/ssh-config/branch/master/graph/badge.svg?token=RMyTgcL8Kg)](https://codecov.io/gh/cyjake/ssh-config)
 
@@ -93,6 +95,28 @@ suggested that the general settings shall be at the end of your config file.
 The `IdentityFile` parameter always contain an array to make possible multiple
 `IdentityFile` settings to be able to coexist.
 
+#### Case-Insensitive Matching
+
+OpenSSH treats configuration directives case-insensitively. By default, `compute()`
+preserves the original case from the config file. To normalize directive names to
+lowercase (matching OpenSSH behavior), use the `ignoreCase` option:
+
+```js
+const config = SSHConfig.parse(`
+  Host example
+    hOsTnaME 1.2.3.4
+    USER admin
+`)
+
+// Default - preserves original case
+config.compute('example')
+// => { hOsTnaME: '1.2.3.4', USER: 'admin' }
+
+// With ignoreCase - lowercase to match OpenSSH
+config.compute('example', { ignoreCase: true })
+// => { hostname: '1.2.3.4', user: 'admin' }
+```
+
 ### `.find` sections by Host or Match
 
 **NOTICE**: This method is provided to find the corresponding section in the

package/{src → dist}/glob.d.ts

@@ -2,8 +2,8 @@
  * A helper function to match input against [pattern-list](https://www.freebsd.org/cgi/man.cgi?query=ssh_config&sektion=5#PATTERNS).
  * According to `man ssh_config`, negated patterns shall be matched first.
  *
- * @param {string|string[]} patternList
- * @param {string} str
+ * @param {string|string[]} patternList one or more glob patterns to match
+ * @param {string} text the text to match
  */
 declare function glob(patternList: string | string[], text: string): boolean;
 export default glob;

package/{src → dist}/glob.js

@@ -17,8 +17,8 @@ function match(pattern, text) {
  * A helper function to match input against [pattern-list](https://www.freebsd.org/cgi/man.cgi?query=ssh_config&sektion=5#PATTERNS).
  * According to `man ssh_config`, negated patterns shall be matched first.
  *
- * @param {string|string[]} patternList
- * @param {string} str
+ * @param {string|string[]} patternList one or more glob patterns to match
+ * @param {string} text the text to match
  */
 function glob(patternList, text) {
     const patterns = Array.isArray(patternList) ? patternList : patternList.split(/,/);

package/dist/glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../src/glob.ts"],"names":[],"mappings":";;AACA,SAAS,WAAW,CAAC,IAAY,EAAE,KAAa;IAC9C,KAAK,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,CAAA;IAChE,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,KAAK,CAAC,OAAe,EAAE,IAAY;IAC1C,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,eAAe,CAAC,CAAA;IAC/C,OAAO,GAAG,OAAO;SACd,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC;SACpB,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IAEvB,OAAO,IAAI,MAAM,CAAC,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACvD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,IAAI,CAAC,WAA8B,EAAE,IAAY;IACxD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAElF,+HAA+H;IAC/H,IAAI,MAAM,GAAG,KAAK,CAAA;IAClB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,CAAA;QAEhC,IAAI,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;YAC5C,OAAO,KAAK,CAAA;QACd,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;YAChC,uFAAuF;YACvF,MAAM,GAAG,IAAI,CAAA;QACf,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,kBAAe,IAAI,CAAA"}

package/dist/ssh-config.d.ts

@@ -0,0 +1,199 @@
+import { Buffer } from 'node:buffer';
+import glob from './glob.ts';
+/**
+ * A type of line in an ssh-config file. Differentiates between directives,
+ * comments, and empty lines.
+ */
+export declare enum LineType {
+    /** line with a directive in an ssh-config file */
+    DIRECTIVE = 1,
+    /** line with a comment in an ssh-config file */
+    COMMENT = 2,
+    /** empty line in an ssh-config file */
+    EMPTY = 3
+}
+/** A separator character in a directive. */
+export type Separator = ' ' | '=' | '\t';
+/**
+ * A directive in an ssh-config file. This is the main type of element in the
+ * file. The directive primarily consists of a
+ * {@link Directive.param | parameter}, and a {@link Directive.value | value},
+ * much like a key-value pair.
+ *
+ * We additionally keep track of a few other fields in order to print out a
+ * directive exactly as it was read, even though the used syntax is equivalent.
+ */
+export interface Directive {
+    /** type of line, always {@link LineType.DIRECTIVE} */
+    type: LineType.DIRECTIVE;
+    /** unrelated string encountered before this directive */
+    before: string;
+    /** unrelated string encountered after this directive */
+    after: string;
+    /** parameter name of this directive */
+    param: string;
+    /** separator char used in this directive */
+    separator: Separator;
+    /** the actual value of this directive */
+    value: string | {
+        val: string;
+        separator: string;
+        quoted?: boolean;
+    }[];
+    /** whether or not quotes were used for the directive value */
+    quoted?: boolean;
+}
+/**
+ * A section is a Host or Match directive in an ssh-config file. It includes a
+ * reference to the contained config via {@link Section.config}.
+ */
+export interface Section extends Directive {
+    /** the config contained in this section */
+    config: SSHConfig;
+}
+/**
+ * Represents a Match directive in an ssh-config file. It includes a reference
+ * to the contained config via {@link Section.config}, and a map of all match
+ * criteria via {@link Match.criteria}.
+ */
+export interface Match extends Section {
+    /** the match criteria contained in this Match section */
+    criteria: Record<string, string | {
+        /** the value of this match criterion */
+        val: string;
+        /** separator used for this match criterion */
+        separator: string;
+        /** whether this match criterion was quoted */
+        quoted?: boolean;
+    }[]>;
+}
+/**
+ * A comment in an ssh-config file. Stores the content of the comment as a
+ * string in {@link Comment.content}.
+ */
+export interface Comment {
+    /** type of line, always {@link LineType.COMMENT} */
+    type: LineType.COMMENT;
+    /** unrelated string encountered before this directive */
+    before: string;
+    /** unrelated string encountered after this directive */
+    after: string;
+    /** content of the comment */
+    content: string;
+}
+/**
+ * An empty or whitespace-only line in an ssh-config file. This is mainly used
+ * to represent empty config ssh-config files. The actual whitespace characters
+ * is usually stored in the {@link Empty.before | before} field. Storing it in
+ * the {@link Empty.after | after} field is permitted, too.
+ */
+export interface Empty {
+    /** type of line, always {@link LineType.COMMENT} */
+    type: LineType.EMPTY;
+    /** unrelated string encountered before this directive */
+    before: string;
+    /** unrelated string encountered after this directive */
+    after: string;
+}
+/**
+ * A single line in an ssh-config file. The union can be discrimiated via its
+ * `type` property of type {@link LineType}.
+ */
+export type Line = Match | Section | Directive | Comment | Empty;
+/**
+ * Options for finding a {@link Section} via Host or Match.
+ */
+export interface FindOptions {
+    /** the host to look for */
+    Host?: string;
+}
+/**
+ * Options for querying an SSH config via host and user.
+ */
+export interface MatchOptions {
+    /** the host of the query */
+    Host: string;
+    /** the user of the query */
+    User?: string;
+}
+/**
+ * Options for computing SSH config results.
+ */
+export interface ComputeOptions {
+    /** when true, normalizes directive names to lowercase to match OpenSSH behavior */
+    ignoreCase?: boolean;
+}
+/**
+ * Represents parsed SSH config. Main element of this library.
+ *
+ * A parsed SSH config is modelled as an array of {@link Line}s.
+ */
+export default class SSHConfig extends Array<Line> {
+    /** shortcut to access {@link LineType.DIRECTIVE} */
+    static readonly DIRECTIVE: LineType.DIRECTIVE;
+    /** shortcut to access {@link LineType.COMMENT} */
+    static readonly COMMENT: LineType.COMMENT;
+    /** shortcut to access {@link LineType.EMPTY} */
+    static readonly EMPTY: LineType.EMPTY;
+    /**
+     * Parse SSH config text into structured object.
+     */
+    static parse(text: string | Buffer): SSHConfig;
+    /**
+     * Stringify structured object into SSH config text.
+     */
+    static stringify(config: SSHConfig): string;
+    /**
+     * Query SSH config by host.
+     */
+    compute(host: string): Record<string, string | string[]>;
+    /**
+     * Query SSH config by host and user.
+     */
+    compute(opts: MatchOptions, computeOpts?: ComputeOptions): Record<string, string | string[]>;
+    /**
+     * Query SSH config by host with options.
+     */
+    compute(host: string, computeOpts?: ComputeOptions): Record<string, string | string[]>;
+    /**
+     * Find by Host or Match.
+     */
+    find(opts: FindOptions): Line | undefined;
+    /**
+     * Find by search function.
+     * @param predicate Function to check against each line; should return a truthy value when a
+     * matching line is given.
+     */
+    find(predicate: (line: Line, index: number, config: Line[]) => unknown): Line | undefined;
+    /**
+     * Remove section by Host or Match.
+     */
+    remove(opts: FindOptions): Line[] | undefined;
+    /**
+     * Remove section by search function.
+     * @param predicate Function to check against each line; should return a truthy value when a
+     * matching line is given.
+     */
+    remove(predicate: (line: Line, index: number, config: Line[]) => unknown): Line[] | undefined;
+    /**
+     * Convert this SSH config to its textual presentation via {@link stringify}.
+     */
+    toString(): string;
+    /**
+     * Append new section to existing SSH config.
+     */
+    append(opts: Record<string, string | string[]>): SSHConfig;
+    /**
+     * Prepend new section to existing SSH config.
+     */
+    prepend(opts: Record<string, string | string[]>, beforeFirstSection?: boolean): SSHConfig;
+}
+/**
+ * Parse SSH config text into structured object.
+ */
+export declare function parse(text: string | Buffer): SSHConfig;
+/**
+ * Stringify structured object into SSH config text.
+ */
+export declare function stringify(config: SSHConfig): string;
+export { glob, SSHConfig };