wingfoil 0.2.1

package/dist/dna/mutate.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyDnaMutation = applyDnaMutation;
+const path_1 = require("./path");
+/** A refusal, in the one shape every branch below returns. */
+function refuse(message) {
+    return { ok: false, message };
+}
+/** Deep-clone the document so no branch can leave a half-applied mutation behind on a refusal. */
+function clone(dna) {
+    return structuredClone(dna);
+}
+/** Coerce one `--entry-<field>` option string into the shape the entry schema declares for it. */
+function coerce(raw, kind) {
+    if (kind === 'string-list')
+        return splitList(raw);
+    if (kind === 'number') {
+        const parsed = Number(raw);
+        return Number.isFinite(parsed) ? parsed : raw;
+    }
+    if (kind === 'boolean') {
+        if (raw === 'true')
+            return true;
+        if (raw === 'false')
+            return false;
+        return raw;
+    }
+    return raw;
+}
+/**
+ * Split a comma-separated option value — the shape used **only** where the schema declares
+ * `z.array(z.string())` (`paths.*`, `team.members[].roles`, `team.agents[].executes_as`). The precedent
+ * is `directive assign --directive testing,code-quality` (`task-056-role-based-directive-assignment`),
+ * so the CLI has one comma convention rather than two.
+ */
+function splitList(raw) {
+    return raw
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+/** The text-edit path for a target, with every collection segment replaced by the entry's resolved index. */
+function textPath(dna, target) {
+    const steps = [];
+    let node = dna;
+    for (const segment of target.segments) {
+        if (Array.isArray(node)) {
+            const index = node.findIndex((entry) => isRecord(entry) && entry.name === segment);
+            steps.push({ index });
+            node = node[index];
+        }
+        else {
+            steps.push({ key: segment });
+            node = isRecord(node) ? node[segment] : undefined;
+        }
+    }
+    return steps;
+}
+/** Whether `value` is a plain object (not null, not an array). */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The container a path's last segment lives in.
+ *
+ * A **declared but absent** object on the way is created — that is what lets
+ * `dna set project.license --value MIT` fill an optional section the document omits — and this is deliberately
+ * NOT the creation `bug-084` filed: every segment here has already been resolved against the schema by
+ * `resolveDnaPath`, so nothing the schema does not declare can reach this function. An existing array is
+ * descended into by entry name rather than replaced, which is exactly what the old traversal got wrong.
+ */
+function containerFor(dna, segments) {
+    let node = dna;
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        const segment = segments[i];
+        if (Array.isArray(node)) {
+            const index = node.findIndex((entry) => isRecord(entry) && entry.name === segment);
+            node = node[index];
+            continue;
+        }
+        const child = node[segment];
+        if (Array.isArray(child) || isRecord(child)) {
+            node = child;
+            continue;
+        }
+        const created = {};
+        node[segment] = created;
+        node = created;
+    }
+    return node;
+}
+/**
+ * Read the list at `segments`, or `[]` when the schema declares it and the document omits it — which
+ * is how `dna add paths.tests --value test/` fills a category the file leaves out.
+ *
+ * The container is always a MAPPING: a list is reached through a mapping key, either a section's
+ * (`paths.sources`) or an entry's (`team.members.<name>.roles`), never as an element of another list,
+ * because the schema declares no list of lists and `resolveDnaPath` refuses one if it ever does.
+ */
+function listAt(dna, target) {
+    const container = containerFor(dna, target.segments);
+    const key = target.segments[target.segments.length - 1];
+    const current = container[key];
+    const items = Array.isArray(current) ? current : [];
+    container[key] = items;
+    return { key, items };
+}
+/** Apply `fields` to `entry`, refusing an option the collection's entry schema does not declare. */
+function applyFields(entry, fields, declared, collectionPath) {
+    for (const name of Object.keys(fields)) {
+        if (name === 'name') {
+            return `'name' is an entry's identity, not a field to update: it is what the path '${collectionPath}.<name>' addresses. Remove the entry and add it under the new name.`;
+        }
+        const field = declared.find((candidate) => candidate.name === name);
+        if (field === undefined) {
+            const known = declared.filter((candidate) => candidate.name !== 'name').map((candidate) => `--${(0, path_1.dnaEntryOptionName)(candidate.name)}`);
+            return `'--${(0, path_1.dnaEntryOptionName)(name)}' is not a field of '${collectionPath}' entries; they carry ${known.join(', ')}`;
+        }
+        entry[name] = coerce(fields[name], field.kind);
+    }
+    return undefined;
+}
+/**
+ * Apply one `add`/`remove`/`update` to `dna`, returning the new document and the minimal text edit that
+ * expresses it — or a refusal message the caller reports at exit `1` (`spec-005` §1, as ruled on
+ * `bug-076`: a well-formed invocation that fails on the content is a logic error, not a usage error).
+ *
+ * Every refusal names what failed and, where there is one, the verb that would have worked — the whole
+ * point of `bug-083`'s repair is that `dna set team.members '[…]'` used to fail with
+ * `expected array, received string` from a schema re-validation, which says nothing about how to reach
+ * the field.
+ *
+ * `schemaRoot` is passed straight to `resolveDnaPath` and defaults to `DnaYaml` there — the only schema
+ * any caller uses. It is a parameter for the same reason: the semantics below are a function of *a*
+ * schema (which field kinds exist, which are required), so they stay exercisable against shapes
+ * `spec-002` does not declare today rather than resting on an untested claim.
+ */
+function applyDnaMutation(dna, request, schemaRoot) {
+    const resolved = (0, path_1.resolveDnaPath)(dna, request.field, schemaRoot);
+    if (!resolved.ok)
+        return refuse(resolved.message);
+    const target = resolved.target;
+    const fields = request.fields ?? {};
+    const next = clone(dna);
+    switch (target.kind) {
+        case 'section':
+            return refuse(`'${request.field}' is a section of dna.yaml, not a field: name a field inside it (for example '${request.field}.<field>')`);
+        case 'collection':
+            return mutateCollection(next, target, request, fields);
+        case 'entry':
+            return mutateEntry(next, target, request, fields);
+        case 'string-list':
+            return mutateStringList(next, target, request);
+        case 'scalar':
+            return mutateScalar(next, target, request);
+    }
+}
+/** The path ends at an array of objects: `add` creates an entry, `remove` drops one, `update` amends one. */
+function mutateCollection(next, target, request, fields) {
+    const name = request.value;
+    if (name === undefined || name.length === 0) {
+        return refuse(`--value is required at '${target.path}': it names the entry (dl-081: --value is the entry's identity at a collection)`);
+    }
+    const { items } = listAt(next, target);
+    const index = items.findIndex((entry) => isRecord(entry) && entry.name === name);
+    const declared = target.entryFields ?? [];
+    if (request.verb === 'add') {
+        if (index >= 0) {
+            return refuse(`'${target.path}' already carries an entry named '${name}' — entry names are unique (dl-081); use \`dna update\` to change it`);
+        }
+        const entry = { name };
+        const failure = applyFields(entry, fields, declared, target.path);
+        if (failure !== undefined)
+            return refuse(failure);
+        const missing = declared
+            .filter((field) => field.required && field.name !== 'name' && entry[field.name] === undefined)
+            .map((field) => `--${(0, path_1.dnaEntryOptionName)(field.name)}`);
+        if (missing.length > 0) {
+            return refuse(`an entry of '${target.path}' requires ${missing.join(', ')}`);
+        }
+        const ordered = orderBySchema(entry, declared);
+        items.push(ordered);
+        return { ok: true, dna: next, edit: { kind: 'append-items', path: textPath(next, target), items: [ordered] } };
+    }
+    if (index < 0) {
+        return refuse(`no entry named '${name}' in '${target.path}'`);
+    }
+    if (request.verb === 'remove') {
+        items.splice(index, 1);
+        return { ok: true, dna: next, edit: { kind: 'remove-items', path: textPath(next, target), indexes: [index] } };
+    }
+    if (Object.keys(fields).length === 0) {
+        const known = declared.filter((field) => field.name !== 'name').map((field) => `--${(0, path_1.dnaEntryOptionName)(field.name)}`);
+        return refuse(`\`dna update ${target.path} --value ${name}\` carries no change: pass one of ${known.join(', ')}`);
+    }
+    const entry = items[index];
+    const failure = applyFields(entry, fields, declared, target.path);
+    if (failure !== undefined)
+        return refuse(failure);
+    return { ok: true, dna: next, edit: entryFieldEdit(next, target, index, fields, declared) };
+}
+/** The path ends at one entry (`modules.core`): the path already says which, so `--value` would repeat it. */
+function mutateEntry(next, target, request, fields) {
+    const collectionPath = target.collectionPath;
+    const name = target.segments[target.segments.length - 1];
+    if (request.verb === 'add') {
+        return refuse(`'${target.path}' already exists: \`dna add ${collectionPath} --value <name>\` creates a new entry, \`dna update\` changes this one`);
+    }
+    if (request.value !== undefined) {
+        return refuse(`--value says nothing the path '${target.path}' has not already said: drop it, or address the collection with \`${collectionPath} --value ${name}\``);
+    }
+    // The collection resolved on the way to the entry, so this re-resolution against the clone cannot
+    // fail; it is done rather than threaded through because the clone's array is a different object.
+    const collection = (0, path_1.resolveDnaPath)(next, collectionPath);
+    if (!collection.ok)
+        return refuse(collection.message);
+    const { items } = listAt(next, collection.target);
+    const index = target.entryIndex;
+    if (request.verb === 'remove') {
+        items.splice(index, 1);
+        return { ok: true, dna: next, edit: { kind: 'remove-items', path: textPath(next, collection.target), indexes: [index] } };
+    }
+    const declared = target.entryFields ?? [];
+    if (Object.keys(fields).length === 0) {
+        const known = declared.filter((field) => field.name !== 'name').map((field) => `--${(0, path_1.dnaEntryOptionName)(field.name)}`);
+        return refuse(`\`dna update ${target.path}\` carries no change: pass one of ${known.join(', ')}`);
+    }
+    const entry = items[index];
+    const failure = applyFields(entry, fields, declared, collectionPath);
+    if (failure !== undefined)
+        return refuse(failure);
+    return { ok: true, dna: next, edit: entryFieldEdit(next, collection.target, index, fields, declared) };
+}
+/** The path ends at an array of strings: `add` appends, `remove` drops, `update` replaces the list. */
+function mutateStringList(next, target, request) {
+    if (request.value === undefined) {
+        return refuse(`--value is required at '${target.path}'`);
+    }
+    const values = splitList(request.value);
+    if (values.length === 0) {
+        return refuse(`--value is required at '${target.path}'`);
+    }
+    const { items } = listAt(next, target);
+    const path = textPath(next, target);
+    if (request.verb === 'update') {
+        items.splice(0, items.length, ...values);
+        return { ok: true, dna: next, edit: { kind: 'replace-list', path, items: values } };
+    }
+    if (request.verb === 'add') {
+        for (const value of values) {
+            if (items.includes(value))
+                return refuse(`'${target.path}' already contains '${value}'`);
+        }
+        items.push(...values);
+        return { ok: true, dna: next, edit: { kind: 'append-items', path, items: values } };
+    }
+    const indexes = [];
+    for (const value of values) {
+        const index = items.indexOf(value);
+        if (index < 0)
+            return refuse(`'${target.path}' does not contain '${value}'`);
+        indexes.push(index);
+    }
+    const removed = new Set(indexes);
+    const kept = items.filter((_item, index) => !removed.has(index));
+    items.splice(0, items.length, ...kept);
+    return { ok: true, dna: next, edit: { kind: 'remove-items', path, indexes: [...indexes].sort((a, b) => a - b) } };
+}
+/** The path ends at a single value: `update` writes it, `remove` drops it when the schema allows, `add` does not apply. */
+function mutateScalar(next, target, request) {
+    const key = target.segments[target.segments.length - 1];
+    const container = containerFor(next, target.segments);
+    if (request.verb === 'add') {
+        return refuse(`'${target.path}' holds a single value: use \`dna update ${target.path} --value <v>\` (or \`dna set ${target.path} --value <v>\`)`);
+    }
+    if (request.verb === 'remove') {
+        if (target.required) {
+            return refuse(`'${target.path}' is required by the dna.yaml schema and cannot be removed`);
+        }
+        if (!(key in container)) {
+            return refuse(`'${target.path}' is not set, so there is nothing to remove`);
+        }
+        delete container[key];
+        return { ok: true, dna: next, edit: { kind: 'delete-key', path: textPath(next, target) } };
+    }
+    if (request.value === undefined) {
+        return refuse(`--value is required at '${target.path}'`);
+    }
+    container[key] = request.value;
+    return { ok: true, dna: next, edit: { kind: 'set-scalar', path: textPath(next, target), value: request.value } };
+}
+/** Rewrite an entry's keys into schema order, so the same call always renders the same bytes (REQ-SYS-07). */
+function orderBySchema(entry, declared) {
+    const ordered = {};
+    for (const field of declared) {
+        if (entry[field.name] !== undefined)
+            ordered[field.name] = entry[field.name];
+    }
+    for (const key of Object.keys(entry)) {
+        if (ordered[key] === undefined)
+            ordered[key] = entry[key];
+    }
+    return ordered;
+}
+/** One `set-scalar` per changed entry field, batched — the text editor applies them in order. */
+function entryFieldEdit(dna, collection, index, fields, declared) {
+    const base = [...textPath(dna, collection), { index }];
+    const edits = Object.keys(fields).map((name) => {
+        const field = declared.find((candidate) => candidate.name === name);
+        return {
+            kind: 'set-scalar',
+            path: [...base, { key: name }],
+            value: coerce(fields[name], field?.kind ?? 'string'),
+        };
+    });
+    return edits.length === 1 ? edits[0] : { kind: 'batch', edits };
+}
+//# sourceMappingURL=mutate.js.map

package/dist/dna/mutate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutate.js","sourceRoot":"","sources":["../../src/dna/mutate.ts"],"names":[],"mappings":"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"}

package/dist/dna/path.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Schema-driven DNA path resolution — the single traversal every DNA **write** goes through
+ * (`dna set`, and `dna add|remove|update` since task-093-dna-mutation-surface-add-remove-update).
+ *
+ * It exists because the previous traversal had no notion of the schema at all: `setDnaValue` walked a
+ * dotted path treating every segment as an object key and **created** an object for any segment it
+ * could not descend into, so `dna set tech_stack.cli.framework Commander` (the then-current spelling,
+ * before `dl-082` moved the value into `--value`) wrote `stacks.cli.framework`
+ * — a key no schema declares — and committed it at exit `0`
+ * (`bug-084-dna-key-alias-writes-unschemad-keys`). `dl-081-dna-mutation-surface-shape`'s ratification
+ * makes the repair a **precondition** of the mutation surface rather than a follow-up to it: under
+ * add/remove/update semantics one cannot add to a collection that does not exist, so the traversal
+ * must be structure-aware and non-creating.
+ *
+ * The rule it implements, in the ratification's own words: **the DNA pillar accepts unknown keys when
+ * reading a document and refuses to write one.** Pass-through on read stays exactly as
+ * `spec-002-dna-yaml-schema` declares it (every node is `.passthrough()`, so a file written by a newer
+ * WingFoil still loads); it is the write side that is closed.
+ *
+ * Two further properties this module owns:
+ *
+ * - **Entries are addressed by `name`, never by index** (`dl-081`, settled in its approve commit).
+ *   `team.members.roberto.roles` reaches one member's role list; `team.members.2.roles` does not
+ *   resolve at all, because an index shifts the moment an entry is removed and a path written today
+ *   would address a different entry tomorrow.
+ * - **A path segment may be quoted, and a quoted segment is taken verbatim, dots included**
+ *   (`dl-083-dotted-entry-names-in-paths`, task-099). `stacks.technologies."Node.js".version`
+ *   addresses the entry named `Node.js` — a name this repository's own `dna.yaml` carries, along with
+ *   `Commander.js` and `AI agent (Claude/Cursor/etc.)`, which is why the alternative of forbidding
+ *   dots in `name` was declined. The grammar lives in `splitDnaPath` (`./set.ts`); this module is one
+ *   of its three callers and adds nothing to it.
+ * - **The schema is the only source of truth.** The traversal reads `DnaYaml` itself (Zod v4 exposes
+ *   `def.shape` / `def.element` / `def.innerType`, and does so through `.passthrough()` and
+ *   `.superRefine()` alike), never a hand-written field table, so the write surface cannot drift from
+ *   the schema it writes as `spec-002` evolves.
+ *
+ * Pure and deterministic (REQ-SYS-07): no wall-clock, no randomness, no filesystem, and the document
+ * it is handed is never mutated — on a refusal as much as on a success.
+ */
+import type { z } from 'zod';
+/**
+ * The prefix every schema-derived entry-field option carries: `--entry-<field>`, spelled with the
+ * schema's own field name (`--entry-executes_as`, not `--entry-executes-as`).
+ *
+ * It exists because the option set is **derived** — `dnaEntryOptionNames()` reads `spec-002`'s entry
+ * schemas — while the global flags are **declared** (`spec-008` §2), and the two namespaces had no
+ * reason to stay disjoint. They did not: `TechEntry` declares `version`, so
+ * `dna add stacks.technologies --value Zod --category validation --version 4.0` reached Commander's
+ * program-level `-V, --version`, printed the CLI version, exited `0` and wrote nothing, while
+ * `--help` advertised the option as working. Measured on a real `wingfoil init` project.
+ *
+ * **It is not a `version` problem.** Driving a synthetic Commander tree with one subcommand option per
+ * global flag shows three distinct outcomes, two of them silent: `--version` fires the program's own
+ * action and exits; `--format` and `--verbose` are swallowed by the program-level option and simply
+ * do not appear in the subcommand's parsed options; `--color` and a non-colliding name survive. So
+ * the failure mode is "the value vanishes", and any future entry field named after any current or
+ * future global flag inherits it.
+ *
+ * **What an unprefixed spelling therefore does, which is two different things.** A name §2 does not
+ * declare (`--category`, `--email`) is refused by Commander as an unknown option, exit `1`. A name §2
+ * DOES declare — today exactly one, `version`, which is the whole overlap between the derived set and
+ * the global set — is consumed by the global instead and is never reported: that is the silent no-op
+ * above. `spec-008` §9's option row states both halves, because stating only the first is a claim
+ * that is false for the very field the section uses as its example.
+ *
+ * **Why a prefix rather than refusing to register a shadowing name.** Refusal trades a silent failure
+ * for a loud hole: `version` is a field `spec-002` declares on `TechEntry`, so refusing it would make
+ * a schema-declared field permanently unwritable, and `dl-081` ratified a surface that reaches every
+ * collection. Refusal is also unstable in the wrong direction — the global set can grow (`spec-008`
+ * §2 is amendable), and a new global flag would then retroactively disable an entry field that had
+ * been writable, breaking scripts with no code change nearby. A prefix removes the collision **by
+ * construction**, for every present and future name on both sides, and it is uniform rather than
+ * conditional: a rule that prefixed only the colliding names would make an option's spelling depend
+ * on a table declared elsewhere, so adding a global flag later would silently RENAME an existing
+ * option. `test/cli/derived-option-namespace.test.ts` holds the invariant that keeps this true,
+ * derived from the built program rather than from a hand-listed copy of `spec-008` §2.
+ */
+export declare const DNA_ENTRY_OPTION_PREFIX: "entry-";
+/** The CLI/MCP option name carrying one entry field — the single place the prefix is applied. */
+export declare function dnaEntryOptionName(field: string): string;
+/** The entry field an option name carries, or `undefined` when it is not an entry-field option. */
+export declare function dnaEntryFieldOfOption(option: string): string | undefined;
+/** The kind of node a resolved path lands on — what a verb is allowed to do there. */
+export type DnaTargetKind = 
+/** An object node (`project`, `team`, `paths`): a section, not a writable field. */
+'section'
+/** A single value (`project.license`, `modules.core.path`, `version`). */
+ | 'scalar'
+/** An array of strings (`paths.sources`, `team.members.<name>.roles`). */
+ | 'string-list'
+/** An array of objects (`modules`, `team.members`, `stacks.technologies`). */
+ | 'collection'
+/** One element of a collection, addressed by its `name`. */
+ | 'entry';
+/** The value shape of one field declared on a collection's entry object. */
+export type DnaFieldKind = 'string' | 'number' | 'boolean' | 'string-list' | 'other';
+/** One field a collection's entries may carry, as the schema declares it (used to build the CLI options). */
+export interface DnaEntryField {
+    readonly name: string;
+    readonly kind: DnaFieldKind;
+    readonly required: boolean;
+}
+/** Where a dotted path landed: what kind of node, what is there today, and what may be written into it. */
+export interface DnaPathTarget {
+    readonly kind: DnaTargetKind;
+    /** The path as given (paths are never rewritten — see {@link DNA_KEY_ALIASES}'s note in `./set.ts`). */
+    readonly path: string;
+    /**
+     * `path` parsed by `splitDnaPath`; for an `entry`, the last segment is the entry's `name`. A quoted
+     * segment contributes its name **without** the delimiters and with its dots intact, so
+     * `stacks.technologies."Node.js".version` yields four segments, not five (`dl-083`, task-099).
+     */
+    readonly segments: readonly string[];
+    /** The value in the document at this path, or `undefined` when the node is declared but absent. */
+    readonly value: unknown;
+    /** Whether the node is actually present in the document (a declared-but-absent node resolves with `false`). */
+    readonly exists: boolean;
+    /** Whether the schema requires this node (`kind: 'scalar'`/`'string-list'`) — i.e. whether it may be removed. */
+    readonly required?: boolean;
+    /** The entry's index inside its collection (`kind: 'entry'`). */
+    readonly entryIndex?: number;
+    /** The fields the entries of this collection may carry, in schema order (`kind: 'collection'` or `'entry'`). */
+    readonly entryFields?: readonly DnaEntryField[];
+    /** The path of the collection an `entry` belongs to (`kind: 'entry'`). */
+    readonly collectionPath?: string;
+}
+/** A resolved target, or the refusal message the caller reports at exit `1` (`spec-005` §1). */
+export type DnaPathResolution = {
+    readonly ok: true;
+    readonly target: DnaPathTarget;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Resolve `keyPath` against `DnaYaml` and `dna`, reporting what a verb may do at the end of it.
+ *
+ * Every refusal names the **full** path (so an error message is greppable against the invocation) and
+ * the part of it that failed. The four refusal families:
+ *
+ * - a segment the schema does not declare — `bug-084`, the reason this module exists;
+ * - a path that tries to descend through a value or through a list of values;
+ * - an index where an entry `name` is expected (`dl-081`: indices are not the addressing form);
+ * - an entry `name` the collection does not carry, or carries more than once. The second is
+ *   unreachable through any CLI/MCP path once `DnaYaml`'s per-collection uniqueness refinement is in
+ *   force (a duplicate-bearing document no longer loads), and is kept because this function is a pure
+ *   helper that can be handed any object — including, in a test, one that never went through the
+ *   loader.
+ *
+ * A **declared but absent** node is not a refusal: it resolves with `exists: false`, which is what lets
+ * `dna set project.license --value MIT` fill an optional section the document happens to omit. That is the
+ * precise line `bug-084` draws — creating a node the schema declares is legitimate; inventing one it
+ * does not declare is the defect.
+ *
+ * `schemaRoot` defaults to `DnaYaml` — the only schema any caller passes — and is a parameter because
+ * the traversal is a function of *a* schema and a document, not of this one: it keeps the
+ * "addressable shape" rules (which node kinds a path may end on, which it may descend through)
+ * testable against shapes `spec-002` does not declare today, rather than leaving them as assertions
+ * nothing exercises.
+ */
+export declare function resolveDnaPath(dna: unknown, keyPath: string, schemaRoot?: z.ZodType): DnaPathResolution;
+/**
+ * Every collection `DnaYaml` declares, as a dotted path — derived from the schema, in a fixed order
+ * (REQ-SYS-07). Used to build the union of `--<entry-field>` options the mutation verbs accept and to
+ * document the surface in `--help`; nothing here is hand-listed, so a collection added to `spec-002`
+ * becomes addressable without touching this module.
+ */
+export declare function dnaCollectionPaths(): readonly string[];
+/**
+ * The union of every field name the entries of every collection may carry, minus `name` (which travels
+ * in `--value`, per `dl-081`'s `--value`-is-the-identity convention), in a fixed order. This is the
+ * `--entry-<field>` option set `dna add`/`dna update` register on both surfaces (see {@link dnaEntryOptionName}).
+ */
+export declare function dnaEntryOptionNames(): readonly string[];
+//# sourceMappingURL=path.d.ts.map

package/dist/dna/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/dna/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAK7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,uBAAuB,EAAG,QAAiB,CAAC;AAEzD,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,mGAAmG;AACnG,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExE;AAED,sFAAsF;AACtF,MAAM,MAAM,aAAa;AACvB,oFAAoF;AAClF,SAAS;AACX,0EAA0E;GACxE,QAAQ;AACV,0EAA0E;GACxE,aAAa;AACf,8EAA8E;GAC5E,YAAY;AACd,4DAA4D;GAC1D,OAAO,CAAC;AAEZ,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,CAAC;AAErF,6GAA6G;AAC7G,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,2GAA2G;AAC3G,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,wGAAwG;IACxG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,mGAAmG;IACnG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,+GAA+G;IAC/G,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iHAAiH;IACjH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,gHAAgH;IAChH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAChD,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAsFzI;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAE,CAAC,CAAC,OAAiB,GAAG,iBAAiB,CA2FhH;AAOD;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,MAAM,EAAE,CActD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAavD"}