wingfoil 0.2.1

package/dist/dna/schema.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DnaYaml = exports.Paths = exports.Team = exports.RoleEntry = exports.AgentEntry = exports.TeamMember = exports.Stacks = exports.MethodologyEntry = exports.TechEntry = exports.Module = exports.Project = void 0;
+/**
+ * DnaYaml schema (spec-002-dna-yaml-schema) — the Project DNA structural map (P2.4). This is one of
+ * the three independent per-pillar schemas task-004-decoupled-pillars keeps decoupled (REQ-SYS-02):
+ * it has no dependency on `memory.yaml`'s or `workflows.yaml`'s schema, and its own validation never
+ * inspects any other file.
+ *
+ * Every object node is `.passthrough()` per spec-009-validation-strategy §2. The TypeScript type is
+ * derived exclusively via `z.infer` (spec-002: "no hand-written duplicate interface").
+ */
+const zod_1 = require("zod");
+/**
+ * An array of named entries in which **no two entries share a `name`**.
+ *
+ * `dl-081-dna-mutation-surface-shape` ratified that entries are addressed by `name`
+ * (`dna update team.members.roberto.roles …`) rather than by index, because an index shifts the moment an
+ * entry is removed and a path written today would address a different entry tomorrow. Uniqueness is
+ * therefore not a nicety but the **prerequisite** that addressing rests on, and the ratification left
+ * the mechanism open: "a uniqueness refinement per collection, or the verbs must refuse on more than
+ * one match".
+ *
+ * This is the refinement, and it is the stronger of the two: it makes the ambiguity *unreachable*
+ * rather than *handled*, so no verb needs a two-match branch that nothing could exercise, and it
+ * protects the readers that are not verbs either — `resolveRoleHolders` (`./roles.ts`), the directive
+ * role bindings, and every future lookup by name. It follows the precedent `spec-002` already sets
+ * with `Team`'s referential `superRefine`: a same-document integrity rule that makes a violating file
+ * fail to load, rather than a rule each consumer re-checks.
+ *
+ * Non-breaking where it matters, measured rather than assumed (task-093 AC4): WingFoil's own
+ * `dna.yaml` carries 38 object entries across these six collections with zero duplicates, and every
+ * `wingfoil init` template scaffolds distinct names (`test/dna/schema-uniqueness.test.ts` pins both).
+ * The same name in DIFFERENT collections stays legal — a module and a role may share one.
+ */
+function uniquelyNamed(entry) {
+    return zod_1.z.array(entry).superRefine((value, ctx) => {
+        const firstSeen = new Map();
+        value.forEach((item, index) => {
+            const name = item?.name;
+            if (typeof name !== 'string')
+                return;
+            const earlier = firstSeen.get(name);
+            if (earlier === undefined) {
+                firstSeen.set(name, index);
+                return;
+            }
+            ctx.addIssue({
+                code: 'custom',
+                message: `duplicate entry name "${name}" (already used at index ${earlier}); entries of a collection are addressed by name, so names must be unique`,
+                path: [index, 'name'],
+            });
+        });
+    });
+}
+/** `project:` — free-form project-identity block (name, description, license, north-star, ...); every field optional. */
+exports.Project = zod_1.z
+    .object({
+    name: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    license: zod_1.z.string().optional(),
+    repository: zod_1.z.string().optional(),
+    methodology: zod_1.z.string().optional(),
+    north_star: zod_1.z.string().optional(),
+})
+    .passthrough();
+/** One `modules[]` entry — a source module (`name`, optional `description`/`path`). */
+exports.Module = zod_1.z
+    .object({
+    name: zod_1.z.string(),
+    description: zod_1.z.string().optional(),
+    path: zod_1.z.string().optional(),
+})
+    .passthrough();
+/** `category` is a free string, not a fixed enum (spec-002) — keeps the schema project-shape-agnostic. */
+exports.TechEntry = zod_1.z
+    .object({
+    name: zod_1.z.string(),
+    category: zod_1.z.string(),
+    version: zod_1.z.string().optional(),
+    notes: zod_1.z.string().optional(),
+})
+    .passthrough();
+/** One `stacks.methodologies[]` entry — a development methodology (`name`, optional `phase`/`notes`). */
+exports.MethodologyEntry = zod_1.z
+    .object({
+    name: zod_1.z.string(),
+    phase: zod_1.z.string().optional(),
+    notes: zod_1.z.string().optional(),
+})
+    .passthrough();
+/** Replaces the old fixed-key `tech_stack` object with two flat, generically-shaped lists. */
+exports.Stacks = zod_1.z
+    .object({
+    technologies: uniquelyNamed(exports.TechEntry).optional(),
+    methodologies: uniquelyNamed(exports.MethodologyEntry).optional(),
+})
+    .passthrough();
+/** One `team.members[]` entry — a human contributor and the `roles` they hold (validated against `team.roles`). */
+exports.TeamMember = zod_1.z
+    .object({
+    name: zod_1.z.string(),
+    email: zod_1.z.string().optional(),
+    roles: zod_1.z.array(zod_1.z.string()),
+})
+    .passthrough();
+/** One `team.agents[]` entry — an AI agent, the roles it `executes_as`, and whether it may hold `approval_authority` (REQ-SEC-03). */
+exports.AgentEntry = zod_1.z
+    .object({
+    name: zod_1.z.string(),
+    executes_as: zod_1.z.array(zod_1.z.string()),
+    approval_authority: zod_1.z.boolean().optional(),
+})
+    .passthrough();
+/** One `team.roles[]` entry — a role in the canonical role catalogue (REQ-SYS-08). */
+exports.RoleEntry = zod_1.z
+    .object({
+    name: zod_1.z.string(),
+    description: zod_1.z.string().optional(),
+})
+    .passthrough();
+/**
+ * `team.roles` is the canonical role catalogue (REQ-SYS-08); every role name referenced by
+ * `members[].roles` and `agents[].executes_as` is semantically validated against it (spec-002 "Role
+ * binding (REQ-SYS-08)"). This is a same-document cross-field rule, so — per spec-009 §1's guidance
+ * that such rules "cannot be expressed as a per-field Zod .regex()/.min()" — it runs as a
+ * `.superRefine()` here, still inside the Zod schema.
+ */
+exports.Team = zod_1.z
+    .object({
+    members: uniquelyNamed(exports.TeamMember),
+    agents: uniquelyNamed(exports.AgentEntry).optional(),
+    roles: uniquelyNamed(exports.RoleEntry),
+})
+    .passthrough()
+    .superRefine((value, ctx) => {
+    const knownRoles = new Set(value.roles.map((role) => role.name));
+    value.members.forEach((member, memberIndex) => {
+        member.roles.forEach((roleName, roleIndex) => {
+            if (!knownRoles.has(roleName)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `team.members[${memberIndex}].roles references undefined role "${roleName}" (not in team.roles)`,
+                    path: ['members', memberIndex, 'roles', roleIndex],
+                });
+            }
+        });
+    });
+    (value.agents ?? []).forEach((agent, agentIndex) => {
+        agent.executes_as.forEach((roleName, roleIndex) => {
+            if (!knownRoles.has(roleName)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `team.agents[${agentIndex}].executes_as references undefined role "${roleName}" (not in team.roles)`,
+                    path: ['agents', agentIndex, 'executes_as', roleIndex],
+                });
+            }
+        });
+    });
+});
+/** Category names are fixed per P2.5, but `.passthrough()` tolerates a future extra category. */
+exports.Paths = zod_1.z
+    .object({
+    sources: zod_1.z.array(zod_1.z.string()).optional(),
+    tests: zod_1.z.array(zod_1.z.string()).optional(),
+    docs: zod_1.z.array(zod_1.z.string()).optional(),
+    config: zod_1.z.array(zod_1.z.string()).optional(),
+    governance: zod_1.z.array(zod_1.z.string()).optional(),
+})
+    .passthrough();
+/** The whole `.wingfoil/dna.yaml` document (P2.4, spec-002) — the Project DNA structural map's root schema. */
+exports.DnaYaml = zod_1.z
+    .object({
+    version: zod_1.z.number().positive(),
+    project: exports.Project.optional(),
+    modules: uniquelyNamed(exports.Module),
+    stacks: exports.Stacks,
+    team: exports.Team,
+    paths: exports.Paths,
+})
+    .passthrough();
+//# sourceMappingURL=schema.js.map

package/dist/dna/schema.js.map

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

package/dist/dna/set.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The first-segment alias `dna show` resolves: `tech_stack` -> `stacks`, the BDD-compatibility alias
+ * spec-002-dna-yaml-schema's Consequences describe (the schema renamed the BDD's `tech_stack` wording
+ * to `stacks`), so `dna show tech_stack` still reads the `stacks` subtree.
+ *
+ * **READ side only, since task-093** (`bug-084-dna-key-alias-writes-unschemad-keys`). It used to be
+ * applied on the write path too, and there it was a trap: `stacks` replaced a fixed-key `tech_stack`
+ * OBJECT, which is a change of shape rather than of name, so rewriting only the first segment
+ * produced a path that resolves nowhere — `dna set tech_stack.cli.framework Commander` wrote
+ * `stacks.cli.framework`, a key no schema declares, through `Stacks`'s `.passthrough()`, at exit 0.
+ * spec-002 says plainly that "any consumer that read `tech_stack.<key>` must now scan" the lists, and
+ * a first-segment alias cannot honour that sentence. The write path therefore does not alias at all;
+ * an old-shape path is refused as the unknown key it is (`src/dna/path.ts`, exit 1).
+ */
+export declare const DNA_KEY_ALIASES: Readonly<Record<string, string>>;
+/** The segments of a dotted DNA path, or the refusal message the caller reports (`splitDnaPath`). */
+export type DnaPathSplit = {
+    readonly ok: true;
+    readonly segments: readonly string[];
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Parse a dotted DNA key path into its segments — the ONE place a path is split, shared by
+ * {@link isValidKeyPath}, {@link setDnaValueInText}'s text resolver and `resolveDnaPath`
+ * (`./path.ts`). It replaced three copies of `keyPath.split('.')`, which is why the quoting rule
+ * below has one definition rather than three chances to disagree.
+ *
+ * **The grammar** (`dl-083-dotted-entry-names-in-paths`, ratified; it exists because
+ * `dl-081-dna-mutation-surface-shape` made an entry's `name` the key it is addressed by, and
+ * `stacks.technologies` really does carry entries named `Node.js` and `Commander.js`):
+ *
+ * - a segment that **begins** with `"` is quoted and ends at the **next** `"`. The quotes are
+ *   delimiters and are not part of the name; between them `.` is an ordinary character, and so is
+ *   everything else;
+ * - the closing `"` must be followed by `.` or by the end of the path;
+ * - a segment that does not begin with `"` ends at the next `.`;
+ * - quoting is optional where it is unnecessary: `team."members".roberto` and `team.members.roberto`
+ *   are the same path.
+ *
+ * **The rule narrows what a path may mean, and for one class of path that is a breaking change.**
+ * Before it, `"` was an ordinary character inside a segment; under it every `"` is a delimiter. Two
+ * measured consequences, neither hypothetical: `isValidKeyPath('modules.co"re')` was `true` and is
+ * now `false`; and where a collection carries an entry named `"a"` beside one named `a` — the schema
+ * permits both, `uniquelyNamed` included — `stacks.technologies."a".category` resolved to the
+ * quote-named entry before and resolves to the **other** entry now, silently rather than by refusing.
+ * `dl-083` accepts the narrowing deliberately (a name containing `"` becomes unaddressable, with no
+ * escape sequence), but accepting it is not the same as nothing having changed.
+ *
+ * At a shell prompt the two quoting layers overlap and are easy to confuse:
+ * `wingfoil dna update 'stacks.technologies."Node.js".version' --value 22.14+` has the **shell's**
+ * single quotes outside and **WingFoil's** double quotes inside. This function sees only the inner
+ * form.
+ *
+ * **Three refusals, and the distinctions between them are load-bearing:**
+ *
+ * - an **empty** segment, quoted (`team.""`) or not (`..language`) — `invalid key path: '<path>'`,
+ *   the message `P2.1-dna-set.feature` scenario 3 pins, unchanged;
+ * - an **unterminated** quote — a segment that opens with `"` and never closes. Refused as
+ *   unterminated rather than taken as a name that happens to begin with a quote, so
+ *   `dna update 'stacks."Node.js'` reports the typo instead of hunting for an entry named `"Node`;
+ * - a `"` **no delimiter can account for**: inside an unquoted segment (`modules.co"re`), or in the
+ *   remainder of a quoted one (`stacks."say "hi""`). A quoted segment may not contain `"` and there
+ *   is **no escape sequence** — `dl-083` accepted that cost deliberately rather than overlooking it —
+ *   so the name being reached for has no spelling at all. The refusal says the **name** is
+ *   unaddressable, not that the path is malformed, because the path is the only spelling an
+ *   impossible request has. A quoted segment that merely fails to span its segment (`"Node.js"x`)
+ *   carries no such `"` and is malformed instead: that is what keeps the unaddressable message true
+ *   every time it is printed.
+ *
+ * All three are usage errors (exit 2, `spec-005-cli-command-contract` §1) — properties of how the
+ * argument is spelled, decided before anything is read. This is a pure function with no side effects,
+ * so the caller owns turning a refusal into that exit code.
+ */
+export declare function splitDnaPath(keyPath: string): DnaPathSplit;
+/**
+ * The path spelling of one segment: quoted when its name contains a `.`, bare otherwise. Used wherever
+ * a refusal echoes part of a path, so the reported prefix can be pasted back into a command — without
+ * it `stacks.technologies.Node.js` would be reported for the entry named `Node.js`, and that re-splits
+ * into four segments and names a different node.
+ *
+ * **It is the inverse of {@link splitDnaPath} on the segments `splitDnaPath` produces — not on every
+ * string**, and the difference is worth stating precisely rather than calling it "the inverse".
+ * Brute-forced over the alphabet `{a, ., "}` up to five characters (363 names): 62 round-trip
+ * unchanged, 294 produce a path `splitDnaPath` refuses, and **7 produce a path that parses back to a
+ * different name** — `"a"` contains no `.`, so it is returned bare and re-parses as `a`; `a"."a`
+ * becomes `"a"."a"`, which is two segments.
+ *
+ * All 7 have a `"` in the name, and that is why the gap is unreachable at the one call site
+ * (`prefixOf`, `./path.ts`), structurally rather than by luck: `prefixOf` is fed
+ * `DnaPathTarget.segments`, which comes from `splitDnaPath`, and a segment it returns can never
+ * contain a `"` — a bare segment containing one is refused as unaddressable, and a quoted segment
+ * ends at the *first* `"`. Measured over the same 363: **0** parse to a segment containing a quote.
+ * So the hardening a general inverse would need is unreachable code, and is deliberately not written;
+ * what is written instead is this note and the `"`-free precondition it rests on.
+ */
+export declare function quoteDnaSegment(name: string): string;
+/**
+ * Whether `keyPath` is a well-formed dotted path — {@link splitDnaPath} reduced to a boolean, so the
+ * predicate and the parser cannot disagree about what "well-formed" means. A malformed path (the
+ * BDD's `..language`, an empty segment, an unterminated or unaccountable quote) is a usage error
+ * (exit 2, spec-005-cli-command-contract §1) the caller rejects before any write; a caller that
+ * reports a message uses `splitDnaPath` directly, because only it knows *which* of the three it was.
+ */
+export declare function isValidKeyPath(keyPath: string): boolean;
+/**
+ * Index within `rest` of the `#` that starts an inline comment, or `-1`. Quote-aware, so a `#`
+ * inside a `'single'`- or `"double"`-quoted scalar is not mistaken for a comment; per the YAML spec
+ * a comment must also be preceded by whitespace (or start the field).
+ *
+ * Exported for `./edit.ts`, the sequence-aware editor added by task-093: both write paths must agree
+ * on where a line's value ends and its comment begins, and two copies of this scanner would be two
+ * chances to disagree.
+ */
+export declare function inlineCommentIndex(rest: string): number;
+/** The value part of a key line's `rest`, with any inline comment and surrounding spaces removed. */
+export declare function valueOf(rest: string): string;
+/**
+ * Set the (alias-resolved) dotted `keyPath` to `value` inside the RAW TEXT of a `dna.yaml`, editing
+ * as few bytes as possible: one line rewritten, or one line inserted. Everything else — every
+ * comment, including the inline `[SPEC]`/`[AUTHORING]` field-provenance annotations, and every blank
+ * line, quote style and alignment — is returned byte-for-byte unchanged.
+ *
+ * This is `dna set`'s primary write path (bug-004): re-serializing the parsed object through
+ * `dump()` is correct but discards every comment token, which silently voids the field-provenance
+ * convention — a `[SPEC]` field may only be removed or renamed after changing the specification it
+ * cites, and that cannot be audited once the annotations are gone. A textual edit also needs no
+ * comment-preserving YAML library, keeping `dl-010-minimal-dependencies` intact.
+ *
+ * Returns `undefined` — deliberately, not as an error — whenever a provably-minimal edit does not
+ * exist, leaving the caller to fall back to the whole-file `dump()`:
+ * - `text` is not a single, valid YAML document;
+ * - the key path is malformed (the caller has already raised the exit-2 usage error for it);
+ * - the value's own YAML form is multi-line;
+ * - the target, or an ancestor of it, is a block/multi-line scalar, opens a nested block, or holds
+ *   an inline scalar the path would have to descend through;
+ * - the parent block is a sequence rather than a mapping;
+ * - the edited text does not read back with the target key holding exactly the intended scalar.
+ *
+ * The result is a pure function of `(text, keyPath, value)` — no wall-clock, randomness or unordered
+ * iteration anywhere on the path (REQ-SYS-07).
+ */
+export declare function setDnaValueInText(text: string, keyPath: string, value: string): string | undefined;
+//# sourceMappingURL=set.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../src/dna/set.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAA4B,CAAC;AAE1F,qGAAqG;AACrG,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAKrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAkC1D;AAYD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD;AAwCD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAevD;AAED,qGAAqG;AACrG,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5C;AAoKD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA2BlG"}