dropsh 0.6.0 → 0.7.0

package/dist/src/core/params/from-parameters.d.ts

@@ -0,0 +1,12 @@
+import type { RawParameter } from "./parse-args.js";
+export interface BuildPayloadInput {
+    /** The resolved operation schema, plugin extensions already applied. */
+    schema: unknown;
+    parameters: RawParameter[];
+    operation: "create" | "update";
+    /** Required for `update`: becomes `data.id`. */
+    id?: string;
+    /** Fallback resource type when the schema carries no `type` const/enum. */
+    resourceType?: string;
+}
+export declare function buildPayloadFromParameters(input: BuildPayloadInput): unknown;

package/dist/src/core/params/from-parameters.js

@@ -0,0 +1,209 @@
+import { ValidationError } from "../../errors.js";
+import { indexSchemaFields, propertiesOf, } from "./schema-fields.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function schemaTypeOf(node) {
+    if (!isRecord(node))
+        return undefined;
+    const t = node.type;
+    if (typeof t === "string")
+        return t;
+    if (Array.isArray(t))
+        return t.find((x) => typeof x === "string" && x !== "null");
+    return undefined;
+}
+/**
+ * Convert one command-line string into the value the leaf schema node asks for.
+ * A non-convertible value is rejected here rather than left for Ajv, because
+ * `--no-validate` must not turn a wrong type into a silently wrong payload.
+ */
+function coerce(node, param, label) {
+    const type = schemaTypeOf(node);
+    if (!param.hasValue) {
+        if (type === "boolean")
+            return true;
+        throw new ValidationError(`missing value for --${label}${type !== undefined ? ` (expected ${type})` : ""}`);
+    }
+    if (type === "boolean") {
+        if (param.value === "true")
+            return true;
+        if (param.value === "false")
+            return false;
+        throw new ValidationError(`--${label} expects true or false, got "${param.value}"`);
+    }
+    if (type === "integer" || type === "number") {
+        const n = Number(param.value);
+        if (param.value.trim() === "" || !Number.isFinite(n)) {
+            throw new ValidationError(`--${label} expects ${type}, got "${param.value}"`);
+        }
+        if (type === "integer" && !Number.isInteger(n)) {
+            throw new ValidationError(`--${label} expects integer, got "${param.value}"`);
+        }
+        return n;
+    }
+    return param.value;
+}
+function parseJsonValue(param) {
+    try {
+        return JSON.parse(param.value);
+    }
+    catch (err) {
+        throw new ValidationError(`--json ${param.path} is not valid JSON: ${err.message}`);
+    }
+}
+/**
+ * Re-emit an object with its keys in the order its subschema declares them, so
+ * the same fields always serialise to the same bytes.
+ */
+function ordered(node, value) {
+    if (Array.isArray(value)) {
+        const items = isRecord(node) ? node.items : undefined;
+        return value.map((entry) => ordered(items, entry));
+    }
+    if (!isRecord(value))
+        return value;
+    const props = propertiesOf(node);
+    const keys = Object.keys(value);
+    const declared = props ? Object.keys(props).filter((k) => keys.includes(k)) : [];
+    const extra = keys.filter((k) => !declared.includes(k)).sort();
+    const out = {};
+    for (const key of [...declared, ...extra]) {
+        out[key] = ordered(props?.[key], value[key]);
+    }
+    return out;
+}
+/**
+ * Walk a dotted path into a field's subschema, rejecting a segment the schema
+ * does not declare. Returns the leaf node the value must satisfy.
+ */
+function resolveLeaf(field, segments) {
+    let node = field.node;
+    for (const segment of segments) {
+        const props = propertiesOf(node);
+        const next = props?.[segment];
+        if (next === undefined) {
+            throw new ValidationError(`unknown sub-property '${segment}' of '${field.name}'${props ? `; known: ${Object.keys(props).join(", ")}` : ""}`);
+        }
+        node = next;
+    }
+    return node;
+}
+function assign(target, segments, value, label) {
+    let cursor = target;
+    for (const segment of segments.slice(0, -1)) {
+        const existing = cursor[segment];
+        if (existing === undefined) {
+            const created = {};
+            cursor[segment] = created;
+            cursor = created;
+        }
+        else if (isRecord(existing)) {
+            cursor = existing;
+        }
+        else {
+            throw new ValidationError(`parameter '${label}' conflicts with an earlier value`);
+        }
+    }
+    const leaf = segments[segments.length - 1];
+    if (leaf in cursor) {
+        throw new ValidationError(`parameter '${label}' was given more than once`);
+    }
+    cursor[leaf] = value;
+}
+function unknownParameter(name, index) {
+    const attributes = [];
+    const relationships = [];
+    for (const field of index.fields.values()) {
+        (field.kind === "attribute" ? attributes : relationships).push(field.name);
+    }
+    throw new ValidationError(`unknown parameter '${name}'. Known attributes: ${attributes.join(", ") || "(none)"}. ` +
+        `Known relationships: ${relationships.join(", ") || "(none)"}.`);
+}
+/**
+ * A relationship parameter is a bare UUID whenever the schema allows exactly one
+ * target type, and `<type>:<uuid>` when it allows several. The UUID itself never
+ * contains a colon, so the split is unambiguous.
+ */
+function resourceIdentifier(field, param) {
+    if (!param.hasValue) {
+        throw new ValidationError(`missing value for --${field.name} (expected a UUID)`);
+    }
+    const allowed = field.targetTypes ?? [];
+    const colon = param.value.lastIndexOf(":");
+    if (colon > 0) {
+        const type = param.value.slice(0, colon);
+        const id = param.value.slice(colon + 1);
+        if (allowed.length > 0 && !allowed.includes(type)) {
+            throw new ValidationError(`'${type}' is not an allowed target type for '${field.name}'; allowed: ${allowed.join(", ")}`);
+        }
+        return { type, id };
+    }
+    if (allowed.length === 0) {
+        throw new ValidationError(`relationship '${field.name}' declares no target type in the schema; pass <type>:<uuid>`);
+    }
+    if (allowed.length > 1) {
+        throw new ValidationError(`relationship '${field.name}' allows several target types (${allowed.join(", ")}); ` +
+            "pass <type>:<uuid>");
+    }
+    return { type: allowed[0], id: param.value };
+}
+export function buildPayloadFromParameters(input) {
+    const index = indexSchemaFields(input.schema);
+    const attributes = {};
+    const relationships = new Map();
+    for (const param of input.parameters) {
+        const segments = param.path.split(".");
+        const name = segments[0];
+        const field = index.fields.get(name);
+        if (!field)
+            unknownParameter(name, index);
+        if (field.kind === "relationship") {
+            if (segments.length > 1) {
+                throw new ValidationError(`relationship '${name}' takes a UUID, not a sub-path ('${param.path}')`);
+            }
+            const collected = relationships.get(name) ?? [];
+            if (collected.length > 0 && field.multiple !== true) {
+                throw new ValidationError(`relationship '${name}' accepts a single value; it was given more than once`);
+            }
+            collected.push(resourceIdentifier(field, param));
+            relationships.set(name, collected);
+            continue;
+        }
+        const tail = segments.slice(1);
+        const leaf = resolveLeaf(field, tail);
+        const value = param.form === "json"
+            ? ordered(leaf, parseJsonValue(param))
+            : coerce(leaf, param, param.path);
+        assign(attributes, segments, value, param.path);
+    }
+    const resourceType = index.resourceType ?? input.resourceType;
+    if (resourceType === undefined) {
+        throw new ValidationError("cannot determine the JSON:API resource type: the schema declares no type and no fallback was given");
+    }
+    const data = { type: resourceType };
+    if (input.operation === "update") {
+        if (input.id === undefined || input.id === "") {
+            throw new ValidationError("update requires the entity id for data.id");
+        }
+        data.id = input.id;
+    }
+    const attributeNode = propertiesOf(propertiesOf(input.schema)?.data)?.attributes;
+    if (Object.keys(attributes).length > 0) {
+        data.attributes = ordered(attributeNode, attributes);
+    }
+    if (relationships.size > 0) {
+        const out = {};
+        for (const name of index.order) {
+            const collected = relationships.get(name);
+            if (!collected)
+                continue;
+            const field = index.fields.get(name);
+            out[name] = {
+                data: field.multiple === true ? collected : collected[0],
+            };
+        }
+        data.relationships = out;
+    }
+    return { data };
+}

package/dist/src/core/params/help.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The `--help` block for the write commands. It documents the *forms* only and
+ * points at `--fields` for the bundle's actual field names: Commander renders
+ * help synchronously, so it cannot resolve a schema, while `--fields` runs in
+ * the action and goes through the normal fetch-and-cache pipeline.
+ */
+export declare const FIELD_PARAMETER_HELP = "\nField parameters (instead of --data):\n  --<field> <value>          set a field, e.g. --title \"Hello\"\n  --<field>=<value>          same; also the form for many fields in one call\n  --<field>.<sub> <value>    set a sub-property, e.g. --body.value \"Text\"\n  --<relationship> <uuid>    reference by UUID; repeat for a multi-valued field\n  --json <field>=<json>      raw JSON value, for arrays of objects\n\nAdd --fields to list this bundle's actual field parameters and exit without\nsending anything. An unknown field name is rejected, never ignored.\n\nA value starting with -- needs the --<field>=<value> form. A field whose name\ncollides with a reserved option (--bundle, --data, --dry-run, --no-validate,\n--fields, --format, --auth-profile, --config, --view-mode, --json) is reachable\nthrough --json <field>=<json> or --data, never as a bare --<field>.\n\nExample:\n  dropsh create node --bundle article --fields\n  dropsh create node --bundle article --title \"Hello\" --body.value \"Text\" --dry-run";
+export interface AttributeDescription {
+    /** The complete command-line spelling, value placeholder included. */
+    parameter: string;
+    /** Dotted path into `data.attributes`. */
+    path: string;
+    type?: string;
+    /** The field's human label, from the schema's `title`. */
+    label?: string;
+    /** Present only when the schema requires the field. */
+    required?: true;
+    /** Present only when the field can be given as a bare `--flag`. */
+    bare_flag?: true;
+}
+export interface RelationshipDescription {
+    parameter: string;
+    path: string;
+    targets: string[];
+    multiple: boolean;
+    /** The relationship's human label, from the schema's `title`. */
+    label?: string;
+    /** Present only when several target types make `<type>:<uuid>` mandatory. */
+    requires_type_prefix?: true;
+}
+export interface FieldsDescription {
+    type?: string;
+    attributes: AttributeDescription[];
+    relationships: RelationshipDescription[];
+}
+/**
+ * Turn a resolved operation schema into the machine-readable field listing that
+ * `--fields` prints: every settable parameter, in schema declaration order.
+ */
+export declare function describeFields(schema: unknown): FieldsDescription;
+/**
+ * Render the field listing as an aligned, human-readable table — what `--fields`
+ * prints by default. `--format json` yields `describeFields` verbatim instead,
+ * for a caller that wants to consume it.
+ */
+export declare function renderFieldsTable(described: FieldsDescription): string;

package/dist/src/core/params/help.js

@@ -0,0 +1,148 @@
+import { indexSchemaFields, propertiesOf } from "./schema-fields.js";
+/**
+ * The `--help` block for the write commands. It documents the *forms* only and
+ * points at `--fields` for the bundle's actual field names: Commander renders
+ * help synchronously, so it cannot resolve a schema, while `--fields` runs in
+ * the action and goes through the normal fetch-and-cache pipeline.
+ */
+export const FIELD_PARAMETER_HELP = `
+Field parameters (instead of --data):
+  --<field> <value>          set a field, e.g. --title "Hello"
+  --<field>=<value>          same; also the form for many fields in one call
+  --<field>.<sub> <value>    set a sub-property, e.g. --body.value "Text"
+  --<relationship> <uuid>    reference by UUID; repeat for a multi-valued field
+  --json <field>=<json>      raw JSON value, for arrays of objects
+
+Add --fields to list this bundle's actual field parameters and exit without
+sending anything. An unknown field name is rejected, never ignored.
+
+A value starting with -- needs the --<field>=<value> form. A field whose name
+collides with a reserved option (--bundle, --data, --dry-run, --no-validate,
+--fields, --format, --auth-profile, --config, --view-mode, --json) is reachable
+through --json <field>=<json> or --data, never as a bare --<field>.
+
+Example:
+  dropsh create node --bundle article --fields
+  dropsh create node --bundle article --title "Hello" --body.value "Text" --dry-run`;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function schemaTypeOf(node) {
+    if (!isRecord(node))
+        return undefined;
+    const t = node.type;
+    if (typeof t === "string")
+        return t;
+    if (Array.isArray(t))
+        return t.find((x) => typeof x === "string" && x !== "null");
+    return undefined;
+}
+function labelOf(node) {
+    if (!isRecord(node))
+        return undefined;
+    return typeof node.title === "string" ? node.title : undefined;
+}
+/** The command-line spelling, including how the value is written. */
+function spell(path, type) {
+    if (type === "array")
+        return `--json ${path}=<json>`;
+    if (type === "boolean")
+        return `--${path} [true|false]`;
+    return `--${path} <value>`;
+}
+function describeAttribute(path, node, required) {
+    const type = schemaTypeOf(node);
+    const label = labelOf(node);
+    return {
+        parameter: spell(path, type),
+        path,
+        ...(type !== undefined ? { type } : {}),
+        ...(label !== undefined ? { label } : {}),
+        ...(required ? { required: true } : {}),
+        ...(type === "boolean" ? { bare_flag: true } : {}),
+    };
+}
+/** An object attribute is settable only through its leaves, so recurse into them. */
+function describeAttributeTree(path, node, required) {
+    const props = schemaTypeOf(node) === "array" ? undefined : propertiesOf(node);
+    if (!props || Object.keys(props).length === 0) {
+        return [describeAttribute(path, node, required)];
+    }
+    const req = isRecord(node) && Array.isArray(node.required) ? node.required : [];
+    return Object.entries(props).flatMap(([sub, subNode]) => describeAttributeTree(`${path}.${sub}`, subNode, required && req.includes(sub)));
+}
+function describeRelationship(field) {
+    const targets = field.targetTypes ?? [];
+    const ambiguous = targets.length !== 1;
+    const label = labelOf(field.node);
+    return {
+        parameter: `--${field.name} ${ambiguous ? "<type>:<uuid>" : "<uuid>"}`,
+        path: field.name,
+        targets,
+        multiple: field.multiple === true,
+        ...(label !== undefined ? { label } : {}),
+        ...(ambiguous ? { requires_type_prefix: true } : {}),
+    };
+}
+/**
+ * Turn a resolved operation schema into the machine-readable field listing that
+ * `--fields` prints: every settable parameter, in schema declaration order.
+ */
+export function describeFields(schema) {
+    const index = indexSchemaFields(schema);
+    const attributeNode = propertiesOf(propertiesOf(schema)?.data)?.attributes;
+    const requiredNames = isRecord(attributeNode) && Array.isArray(attributeNode.required) ? attributeNode.required : [];
+    const attributes = [];
+    const relationships = [];
+    for (const name of index.order) {
+        const field = index.fields.get(name);
+        if (!field)
+            continue;
+        if (field.kind === "attribute") {
+            attributes.push(...describeAttributeTree(name, field.node, requiredNames.includes(name)));
+        }
+        else
+            relationships.push(describeRelationship(field));
+    }
+    return {
+        ...(index.resourceType !== undefined ? { type: index.resourceType } : {}),
+        attributes,
+        relationships,
+    };
+}
+/**
+ * Render the field listing as an aligned, human-readable table — what `--fields`
+ * prints by default. `--format json` yields `describeFields` verbatim instead,
+ * for a caller that wants to consume it.
+ */
+export function renderFieldsTable(described) {
+    const { attributes, relationships } = described;
+    const head = `${described.type ?? "this bundle"} — field parameters`;
+    if (attributes.length === 0 && relationships.length === 0) {
+        return `${head}\n\nThe schema declares no field parameters for this bundle.`;
+    }
+    const rows = [];
+    for (const a of attributes) {
+        const notes = [a.type ?? "", a.required ? "required" : "", a.label ?? ""].filter((n) => n !== "");
+        rows.push([a.parameter, notes.join("  ")]);
+    }
+    const attributeRows = rows.length;
+    for (const r of relationships) {
+        const notes = [
+            r.targets.join(" | ") || "(no target type declared)",
+            r.multiple ? "repeatable" : "",
+            r.label ?? "",
+        ].filter((n) => n !== "");
+        rows.push([r.parameter, notes.join("  ")]);
+    }
+    const width = Math.max(...rows.map(([p]) => p.length)) + 2;
+    const line = ([p, notes]) => notes === "" ? `  ${p}` : `  ${p.padEnd(width)}${notes}`;
+    const out = [head];
+    if (attributeRows > 0) {
+        out.push("", "Attributes:", ...rows.slice(0, attributeRows).map(line));
+    }
+    if (relationships.length > 0) {
+        out.push("", "Relationships (take a UUID):", ...rows.slice(attributeRows).map(line));
+    }
+    return out.join("\n");
+}

package/dist/src/core/params/parse-args.d.ts

@@ -0,0 +1,18 @@
+export interface RawParameter {
+    /** Dotted path into the payload, e.g. "title" or "body.value". */
+    path: string;
+    value: string;
+    /** Which surface syntax produced it; "json" means `value` is raw JSON. */
+    form: "flag" | "json";
+    /**
+     * False for a bare `--field` with no following value. Whether that is legal
+     * depends on the field's schema type, so the decision belongs to the builder.
+     */
+    hasValue: boolean;
+}
+/**
+ * Parse the token stream Commander passes through for unknown options into an
+ * ordered parameter list. Purely syntactic: no schema is consulted, so an
+ * unknown field name is not an error here.
+ */
+export declare function parseFieldArgs(tokens: string[]): RawParameter[];

package/dist/src/core/params/parse-args.js

@@ -0,0 +1,75 @@
+import { ValidationError } from "../../errors.js";
+/**
+ * `--json` is the one collector: it takes `<field>=<json>` pairs rather than a
+ * value of its own, because a raw JSON value cannot be coerced from the leaf
+ * schema type. The collector name is matched before any other handling, so the
+ * pair's left-hand side is an arbitrary field path — including one that collides
+ * with a reserved option, or `json` itself. That makes `--json <field>=<json>` a
+ * second route to such a field besides `--data`; only the bare `--<field>` form
+ * is out of reach.
+ */
+const COLLECTORS = new Set(["json"]);
+function splitPair(pair, collector) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+        throw new ValidationError(`--${collector} expects <field>=<value> pairs, got "${pair}"`);
+    }
+    return { path: pair.slice(0, eq), value: pair.slice(eq + 1) };
+}
+/**
+ * Parse the token stream Commander passes through for unknown options into an
+ * ordered parameter list. Purely syntactic: no schema is consulted, so an
+ * unknown field name is not an error here.
+ */
+export function parseFieldArgs(tokens) {
+    const out = [];
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        if (!token.startsWith("--")) {
+            throw new ValidationError(`unexpected argument "${token}"; field parameters are long options (--<field> <value>)`);
+        }
+        const body = token.slice(2);
+        if (body.length === 0) {
+            throw new ValidationError('"--" is not a field parameter');
+        }
+        const eq = body.indexOf("=");
+        const name = eq === -1 ? body : body.slice(0, eq);
+        if (COLLECTORS.has(name)) {
+            const pairs = [];
+            if (eq !== -1) {
+                pairs.push(body.slice(eq + 1));
+                i += 1;
+            }
+            else {
+                i += 1;
+                while (i < tokens.length && !tokens[i].startsWith("--")) {
+                    pairs.push(tokens[i]);
+                    i += 1;
+                }
+            }
+            if (pairs.length === 0) {
+                throw new ValidationError(`--${name} expects at least one <field>=<value> pair`);
+            }
+            for (const pair of pairs) {
+                const { path, value } = splitPair(pair, name);
+                out.push({ path, value, form: "json", hasValue: true });
+            }
+            continue;
+        }
+        if (eq !== -1) {
+            out.push({ path: name, value: body.slice(eq + 1), form: "flag", hasValue: true });
+            i += 1;
+            continue;
+        }
+        const next = tokens[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            out.push({ path: name, value: next, form: "flag", hasValue: true });
+            i += 2;
+            continue;
+        }
+        out.push({ path: name, value: "", form: "flag", hasValue: false });
+        i += 1;
+    }
+    return out;
+}

package/dist/src/core/params/schema-fields.d.ts

@@ -0,0 +1,20 @@
+export interface FieldDescriptor {
+    name: string;
+    kind: "attribute" | "relationship";
+    /** The field's own subschema, as declared under attributes/relationships. */
+    node: unknown;
+    /** Relationship only: the resource types its `data.type` accepts. */
+    targetTypes?: string[];
+    /** Relationship only: true when `data` is an array. */
+    multiple?: boolean;
+}
+export interface SchemaFieldIndex {
+    /** From `data.properties.type.const`, else the first `enum` entry. */
+    resourceType?: string;
+    fields: Map<string, FieldDescriptor>;
+    /** Schema declaration order: attributes first, then relationships. */
+    order: string[];
+}
+/** The `properties` map of a schema node, or undefined when it has none. */
+export declare function propertiesOf(node: unknown): Record<string, unknown> | undefined;
+export declare function indexSchemaFields(schema: unknown): SchemaFieldIndex;

package/dist/src/core/params/schema-fields.js

@@ -0,0 +1,65 @@
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The `properties` map of a schema node, or undefined when it has none. */
+export function propertiesOf(node) {
+    if (!isRecord(node))
+        return undefined;
+    const props = node.properties;
+    return isRecord(props) ? props : undefined;
+}
+function resourceTypeOf(dataNode) {
+    const typeNode = propertiesOf(dataNode)?.type;
+    if (!isRecord(typeNode))
+        return undefined;
+    if (typeof typeNode.const === "string")
+        return typeNode.const;
+    if (Array.isArray(typeNode.enum) && typeof typeNode.enum[0] === "string") {
+        return typeNode.enum[0];
+    }
+    return undefined;
+}
+/**
+ * A relationship declares its payload under `data`, either as a single resource
+ * identifier object or as an array of them. Both carry the allowed resource
+ * types in their `type` node's `enum`/`const`, which is what lets a bare UUID on
+ * the command line become a complete identifier object.
+ */
+function describeRelationship(name, node) {
+    const dataNode = propertiesOf(node)?.data;
+    const multiple = isRecord(dataNode) && dataNode.type === "array";
+    const itemNode = multiple ? dataNode.items : dataNode;
+    const typeNode = propertiesOf(itemNode)?.type;
+    let targetTypes;
+    if (isRecord(typeNode)) {
+        if (Array.isArray(typeNode.enum)) {
+            targetTypes = typeNode.enum.filter((t) => typeof t === "string");
+        }
+        else if (typeof typeNode.const === "string") {
+            targetTypes = [typeNode.const];
+        }
+    }
+    return {
+        name,
+        kind: "relationship",
+        node,
+        multiple,
+        ...(targetTypes !== undefined ? { targetTypes } : {}),
+    };
+}
+export function indexSchemaFields(schema) {
+    const dataNode = propertiesOf(schema)?.data;
+    const dataProps = propertiesOf(dataNode);
+    const fields = new Map();
+    const order = [];
+    for (const [name, node] of Object.entries(propertiesOf(dataProps?.attributes) ?? {})) {
+        fields.set(name, { name, kind: "attribute", node });
+        order.push(name);
+    }
+    for (const [name, node] of Object.entries(propertiesOf(dataProps?.relationships) ?? {})) {
+        fields.set(name, describeRelationship(name, node));
+        order.push(name);
+    }
+    const resourceType = resourceTypeOf(dataNode);
+    return { fields, order, ...(resourceType !== undefined ? { resourceType } : {}) };
+}

package/dist/src/core/paths.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The user-global dropsh state directory. Single source of that path: the
+ * per-host auth store and the connections directory both hang off it, so the
+ * two cannot drift onto different roots.
+ */
+export declare function defaultStateDir(): string;
+/** Default location of the named-connection files, one `<id>.js` per connection. */
+export declare function defaultConnectionsDir(): string;

package/dist/src/core/paths.js

@@ -0,0 +1,14 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * The user-global dropsh state directory. Single source of that path: the
+ * per-host auth store and the connections directory both hang off it, so the
+ * two cannot drift onto different roots.
+ */
+export function defaultStateDir() {
+    return join(homedir(), ".config", "dropsh");
+}
+/** Default location of the named-connection files, one `<id>.js` per connection. */
+export function defaultConnectionsDir() {
+    return join(defaultStateDir(), "connections");
+}

package/dist/src/index.d.ts

@@ -39,4 +39,16 @@ export interface AuthStatusDeps {
 }
 export declare function authStatus(deps: AuthStatusDeps): Promise<AuthStatusInfo>;
 export declare function buildProgram(opts?: ProgramOptions): Command;
+/**
+ * The config selectors as they appear in raw argv, for the pre-parse plugin
+ * bootstrap — which runs before commander sees any option. It feeds the same
+ * resolver the commands use, so the early and the late resolution cannot answer
+ * differently and load plugins from a different connection than the command
+ * being bootstrapped.
+ */
+export declare function earlyConfigArgs(argv: string[]): {
+    config?: string;
+    connection?: string;
+    connectionsDir?: string;
+};
 export declare function main(): Promise<void>;