@gaia-ai/addon-name-refs 0.11.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @gaia-ai/addon-name-refs
+
+GAIA connection addon: resolve entity NAMES (--label_names, --environment_names) into the relationships that reference them, on the live write, via dropsh's extendOperationSchema and alterRequest hooks.
+
+Part of the GAIA CLI. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all addons. Source: https://git.key-tec.de/keytec/gaia (gaia-cli/).

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+import type { DropSHPlugin } from 'dropsh/plugin';
+export declare function nameRefsPlugin(): DropSHPlugin;

package/dist/src/index.js

@@ -0,0 +1,408 @@
+// GAIA-403: resolve entity NAMES into the relationship that references them, so
+// a skill writes `--label_names work:code` or `--environment_names staging`
+// instead of searching the collection, pulling a UUID out with jq, and
+// hand-building the linkage.
+//
+// Two hooks, deliberately split by what they may do:
+//   extendOperationSchema — OFFLINE. It makes each synthetic field a settable
+//     field parameter. dropsh disk-caches the extended schema (keyed on the
+//     loaded hook plugins), so anything fetched here would go stale; that is why
+//     the synthetic fields carry no enum of names.
+//   alterRequest — the resolution, on the LIVE write only. `--dry-run` returns
+//     before the client, so a dry-run shows the synthetic field unresolved and a
+//     typo surfaces on the live call — atomically: a throw here becomes a
+//     PluginError (exit 6) and nothing is sent.
+//
+// WHERE THIS LIVES. Its own package, `@gaia-ai/addon-name-refs`, carried as a
+// child of `@gaia-ai/addon-essentials` exactly as `@gaia-ai/addon-workspace` is
+// — so no config names it and the single non-auth `plugins[]` entry every
+// committed config already has is unchanged. It contributes no preset
+// accumulator, so it is a plain sibling edge in `PERMITTED_SIBLINGS`.
+//
+// Adding a target is one RESOLVERS entry. The one thing that differs between
+// them is whether a name is unique on its own: `gaia_term` names are, so a name
+// identifies a term outright. `gaia_environment` names are unique only WITHIN A
+// PROJECT (GaiaEnvironmentUniquePerProject), so the same name legitimately
+// exists several times and picking one would be luck rather than resolution —
+// hence `scopeField`, and the narrowing it drives.
+const RESOLVERS = [
+    {
+        field: 'label_names',
+        noun: 'label',
+        relationship: 'labels',
+        type: 'gaia_term--gaia_labels',
+        path: 'gaia_term/gaia_labels',
+        title: 'Label names (comma-separated gaia_labels names; ' +
+            'resolved to labels on the live write)',
+    },
+    {
+        field: 'environment_names',
+        noun: 'environment',
+        relationship: 'environments',
+        type: 'gaia_environment--gaia_environment',
+        path: 'gaia_environment/gaia_environment',
+        title: 'Environment names (comma-separated; unique per project, so an ' +
+            'ambiguous name is narrowed by the project_id of the write — ' +
+            'resolved to environments on the live write)',
+        scopeField: 'project_id',
+    },
+];
+/**
+ * page[limit] bounds the QUERY, not the row count — links.next is the only end
+ * signal. Asking for more than Drupal's `OffsetPage::SIZE_MAX` is not an error,
+ * it is silently clamped to it, so requesting 200 bought nothing and made the
+ * ceiling below misreport itself by 4x. 50 is the number the server will
+ * actually serve.
+ */
+const PAGE_LIMIT = 50;
+const MAX_PAGES = 10;
+/** Rows this resolver will walk before it refuses to resolve at all. */
+const MAX_ROWS = PAGE_LIMIT * MAX_PAGES;
+/**
+ * How many known names an error may list. `gaia_labels` is small; a future
+ * target need not be, and an error nobody can read is an error nobody reads.
+ */
+const NAME_LIST_CAP = 20;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function at(node, ...path) {
+    let cursor = node;
+    for (const key of path) {
+        if (!isRecord(cursor))
+            return undefined;
+        cursor = cursor[key];
+    }
+    return cursor;
+}
+/** The id a relationship points at, for the single-valued relationships used as scopes. */
+function relationshipId(node, field) {
+    const id = at(node, 'relationships', field, 'data', 'id');
+    return typeof id === 'string' ? id : undefined;
+}
+/**
+ * Does this operation schema declare this resolver's relationship over its
+ * target type? Only the multi-valued (`items`) shape is recognised: both
+ * targets are unlimited-cardinality, and the merge below writes an array, so
+ * matching a single-valued relationship here would produce an invalid payload.
+ */
+function declares(schema, ref) {
+    const targets = at(schema, 'properties', 'data', 'properties', 'relationships', 'properties', ref.relationship, 'properties', 'data', 'items', 'properties', 'type', 'enum');
+    return Array.isArray(targets) && targets.includes(ref.type);
+}
+/** `/jsonapi`, however the config spelled it — with, without, or with a trailing slash. */
+function normalisePrefix(raw) {
+    const trimmed = (raw ?? '/jsonapi').replace(/^\/+/, '').replace(/\/+$/, '');
+    return trimmed === '' ? '' : `/${trimmed}`;
+}
+/**
+ * GET one JSON:API document, or fail by name.
+ *
+ * This plugin issues its own reads through `ctx.http` / `ctx.auth`, which is the
+ * only seam the plugin API offers — and it is NOT the seam dropsh's JSON:API
+ * client uses. That client catches a 401 and calls `auth.renew()` once
+ * (`client.js:44-47`); nothing here can, because `AuthAdapter.apply` exposes no
+ * renewal. So an expired token cannot be refreshed transparently mid-write: it
+ * arrives here as a plain non-2xx, and the least this can do is say so instead
+ * of handing an HTML error page to `JSON.parse`.
+ */
+async function fetchDoc(ctx, url, what) {
+    const res = await ctx.http.send(await ctx.auth.apply({
+        method: 'GET',
+        url,
+        headers: { Accept: 'application/vnd.api+json' },
+    }));
+    if (res.status < 200 || res.status >= 300) {
+        const expiry = res.status === 401 || res.status === 403
+            ? ' The access token may have expired: this plugin performs its own reads ' +
+                'and, unlike dropsh’s JSON:API client, cannot renew one, so an expired ' +
+                'token surfaces here instead of being refreshed. Re-authenticate and retry.'
+            : '';
+        throw new Error(`could not read ${what}: HTTP ${res.status} from ${url}.${expiry}`);
+    }
+    try {
+        return JSON.parse(res.body);
+    }
+    catch (cause) {
+        throw new Error(`could not read ${what}: ${url} answered ${res.status} but not JSON (${String(cause)})`);
+    }
+}
+/**
+ * The whole collection as name → candidates. One round trip regardless of how
+ * many names were given, and it yields the known-names list the error needs.
+ */
+async function fetchIndex(ctx, ref) {
+    const prefix = normalisePrefix(ctx.jsonapiPrefix);
+    const fields = ref.scopeField === undefined ? 'name' : `name,${ref.scopeField}`;
+    let url = `${ctx.baseUrl.replace(/\/+$/, '')}${prefix}/${ref.path}` +
+        `?fields[${ref.type}]=${fields}&sort=name&page[limit]=${PAGE_LIMIT}`;
+    const byName = new Map();
+    for (let page = 0; page < MAX_PAGES; page += 1) {
+        const doc = await fetchDoc(ctx, url, `the ${ref.path} vocabulary`);
+        const rows = at(doc, 'data');
+        for (const row of Array.isArray(rows) ? rows : []) {
+            const name = at(row, 'attributes', 'name');
+            const id = isRecord(row) ? row.id : undefined;
+            if (typeof name !== 'string' || typeof id !== 'string')
+                continue;
+            const candidate = {
+                id,
+                scopeId: ref.scopeField === undefined
+                    ? undefined
+                    : relationshipId(row, ref.scopeField),
+            };
+            const bucket = byName.get(name);
+            if (bucket === undefined)
+                byName.set(name, [candidate]);
+            else if (!bucket.some((c) => c.id === id))
+                bucket.push(candidate);
+        }
+        const next = at(doc, 'links', 'next', 'href');
+        if (typeof next !== 'string')
+            return byName;
+        url = next;
+    }
+    throw new Error(`the ${ref.path} collection did not end within ${MAX_PAGES} pages of ` +
+        `${PAGE_LIMIT} (Drupal clamps page[limit] to OffsetPage::SIZE_MAX = ` +
+        `${PAGE_LIMIT}, so the ceiling is ${MAX_ROWS} rows); refusing to resolve ` +
+        `against a truncated list`);
+}
+/** Read the scope off the entity being updated — the fallback when the PATCH omits it. */
+async function fetchScope(req, ctx, scopeField) {
+    const doc = await fetchDoc(ctx, req.url, `the entity being updated`);
+    return relationshipId(at(doc, 'data'), scopeField);
+}
+/** The known-names list an error may print — bounded, and honest about the total. */
+function knownNames(byName) {
+    const names = [...byName.keys()];
+    if (names.length === 0)
+        return '(none)';
+    if (names.length <= NAME_LIST_CAP)
+        return names.join(', ');
+    return `${names.slice(0, NAME_LIST_CAP).join(', ')}, … (${names.length} in total)`;
+}
+function describe(candidates) {
+    return candidates
+        .map((c) => (c.scopeId === undefined ? c.id : `${c.id} (${c.scopeId})`))
+        .join(', ');
+}
+export function nameRefsPlugin() {
+    // Per-instance, not module-level: one CLI invocation performs one write, so
+    // these guard against a second lookup, and they keep tests isolated.
+    const indexes = new Map();
+    const scopes = new Map();
+    /**
+     * Which synthetic fields each bundle was offered, recorded as
+     * `extendOperationSchema` runs. `alterRequest` gets no schema — `RequestContext`
+     * carries only the entity type, the bundle and the operation — so this is the
+     * only way it can know that a `label_names` reaching a `gaia_comment` write is
+     * not a field that bundle has.
+     *
+     * ABSENCE PROVES NOTHING. dropsh disk-caches the extended schema and skips the
+     * hook on a cache hit, so an empty record is the normal case for a repeat
+     * write, not evidence that the bundle declares nothing. The check below is
+     * therefore a NEGATIVE one only: refuse when this instance has positive
+     * evidence to the contrary, never merely because it has none.
+     */
+    const offered = new Map();
+    const bundleKey = (entityType, bundle) => `${entityType ?? ''}/${bundle ?? ''}`;
+    return {
+        id: 'gaia-name-refs',
+        requiredModules: [],
+        async extendOperationSchema(entityType, bundle, _operation, schema) {
+            if (!isRecord(schema))
+                return schema;
+            const matching = RESOLVERS.filter((ref) => declares(schema, ref));
+            // Recorded even when nothing matched — "this bundle was offered nothing"
+            // is exactly the fact `alterRequest` needs.
+            offered.set(bundleKey(entityType, bundle), new Set(matching.map((ref) => ref.field)));
+            if (matching.length === 0)
+                return schema;
+            const data = at(schema, 'properties', 'data');
+            const attributes = at(data, 'properties', 'attributes');
+            if (!isRecord(data) || !isRecord(attributes))
+                return schema;
+            const synthetic = {};
+            for (const ref of matching) {
+                synthetic[ref.field] = { type: 'string', title: ref.title };
+            }
+            return {
+                ...schema,
+                properties: {
+                    ...(isRecord(schema.properties) ? schema.properties : {}),
+                    data: {
+                        ...data,
+                        properties: {
+                            ...(isRecord(data.properties) ? data.properties : {}),
+                            attributes: {
+                                ...attributes,
+                                properties: {
+                                    ...(isRecord(attributes.properties)
+                                        ? attributes.properties
+                                        : {}),
+                                    ...synthetic,
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+        },
+        async alterRequest(req, ctx) {
+            if (ctx.operation !== 'create' && ctx.operation !== 'update')
+                return req;
+            if (typeof req.body !== 'string' || req.body === '')
+                return req;
+            let doc;
+            try {
+                doc = JSON.parse(req.body);
+            }
+            catch {
+                return req;
+            }
+            const data = at(doc, 'data');
+            const attributes = at(data, 'attributes');
+            if (!isRecord(doc) || !isRecord(data) || !isRecord(attributes))
+                return req;
+            const active = RESOLVERS.filter((ref) => attributes[ref.field] !== undefined);
+            if (active.length === 0)
+                return req;
+            const nextAttributes = { ...attributes };
+            const relationships = isRecord(data.relationships)
+                ? { ...data.relationships }
+                : {};
+            const declaredHere = offered.get(bundleKey(ctx.entityType, ctx.bundle));
+            for (const ref of active) {
+                // A name field on a bundle that has no such relationship. Reachable by
+                // a hand-built body or `--no-validate`, since the flag itself only
+                // exists where the schema was extended. Inventing the relationship here
+                // would send a document the server can only answer 422 to, naming a
+                // field the caller never wrote.
+                if (declaredHere !== undefined && !declaredHere.has(ref.field)) {
+                    throw new Error(`${ctx.entityType}/${ctx.bundle} declares no '${ref.relationship}' ` +
+                        `relationship, so '${ref.field}' cannot be resolved on this write. ` +
+                        `Remove it, or write to a bundle that has ${ref.relationship}.`);
+                }
+                delete nextAttributes[ref.field];
+                const names = String(attributes[ref.field])
+                    .split(',')
+                    .map((name) => name.trim())
+                    .filter((name) => name.length > 0);
+                if (names.length === 0)
+                    continue;
+                let index = indexes.get(ref.field);
+                if (index === undefined) {
+                    index = fetchIndex(ctx, ref);
+                    indexes.set(ref.field, index);
+                }
+                const byName = await index;
+                const scopeField = ref.scopeField;
+                // The scope the payload already carries. Free — no round trip — so it
+                // narrows EVERY name, including an unambiguous one: a name that is
+                // unique across the whole collection can still belong to a different
+                // parent than the entity being written, and attaching it silently would
+                // be worse than the round trip we are saving.
+                const payloadScope = scopeField === undefined
+                    ? undefined
+                    : relationshipId(data, scopeField);
+                const resolved = [];
+                for (const name of names) {
+                    const candidates = byName.get(name) ?? [];
+                    const [only, ...rivals] = candidates;
+                    if (only === undefined) {
+                        throw new Error(`${ref.noun} name '${name}' does not exist in the ${ref.path} ` +
+                            `vocabulary. Known names: ${knownNames(byName)}`);
+                    }
+                    if (scopeField === undefined) {
+                        if (rivals.length > 0) {
+                            throw new Error(`${ref.noun} name '${name}' is ambiguous — ${candidates.length} ` +
+                                `entries in ${ref.path} share it. Candidates: ${describe(candidates)}. ` +
+                                `Pass the uuid directly on the ${ref.relationship} relationship instead.`);
+                        }
+                        resolved.push(only.id);
+                        continue;
+                    }
+                    // A scoped resolver ALWAYS establishes a scope — including for a name
+                    // that is unique across the whole collection today. Uniqueness is a
+                    // property of the current rows, not of the name: `staging` is unique
+                    // right up to the moment a second project creates one, and until then
+                    // an unscoped write would attach another project's environment and
+                    // report success. So when the payload carries no scope, read it off
+                    // the entity being updated (memoised: one read per write, however many
+                    // names were given). A create has no entity yet, hence `undefined`.
+                    let scopeId = payloadScope;
+                    if (scopeId === undefined) {
+                        let pending = scopes.get(scopeField);
+                        if (pending === undefined) {
+                            pending =
+                                ctx.operation === 'update'
+                                    ? fetchScope(req, ctx, scopeField)
+                                    : Promise.resolve(undefined);
+                            scopes.set(scopeField, pending);
+                        }
+                        scopeId = await pending;
+                    }
+                    // No scope at all is a hard error, never a fallthrough to "the only
+                    // one there is". Refusing costs a caller one explicit uuid; guessing
+                    // costs them a cross-project attachment they never see.
+                    if (scopeId === undefined) {
+                        throw new Error(rivals.length > 0
+                            ? `${ref.noun} name '${name}' is ambiguous — ${candidates.length} ` +
+                                `entries in ${ref.path} share it and the write carries no ` +
+                                `${scopeField} to narrow them. Candidates: ${describe(candidates)}. ` +
+                                `Pass the uuid directly on the ${ref.relationship} relationship instead.`
+                            : `${ref.noun} name '${name}' cannot be resolved: ${ref.path} names are ` +
+                                `unique only within ${scopeField}, and this write carries no ` +
+                                `${scopeField} to narrow it — being the only '${name}' that exists ` +
+                                `today does not make it this write's. Candidate: ${describe(candidates)}. ` +
+                                `Name the ${scopeField}, or pass the uuid directly on the ` +
+                                `${ref.relationship} relationship instead.`);
+                    }
+                    const [match, ...extra] = candidates.filter((c) => c.scopeId === scopeId);
+                    if (match === undefined) {
+                        const elsewhere = candidates
+                            .map((c) => c.scopeId ?? '(none)')
+                            .join(', ');
+                        throw new Error(`${ref.noun} name '${name}' does not exist in ${scopeField} ` +
+                            `'${scopeId}'. It exists in: ${elsewhere}.`);
+                    }
+                    if (extra.length > 0) {
+                        throw new Error(`${ref.noun} name '${name}' is ambiguous even within ${scopeField} ` +
+                            `'${scopeId}': ${describe([match, ...extra])}. Pass the uuid directly ` +
+                            `on the ${ref.relationship} relationship instead.`);
+                    }
+                    resolved.push(match.id);
+                }
+                const current = at(relationships, ref.relationship, 'data');
+                const existing = Array.isArray(current)
+                    ? current
+                    : current !== undefined
+                        ? [current]
+                        : [];
+                const merged = [];
+                const seen = new Set();
+                for (const entry of [
+                    ...existing,
+                    ...resolved.map((id) => ({ type: ref.type, id })),
+                ]) {
+                    const id = isRecord(entry) ? entry.id : undefined;
+                    if (typeof id !== 'string' || seen.has(id))
+                        continue;
+                    seen.add(id);
+                    merged.push(entry);
+                }
+                if (merged.length > 0) {
+                    relationships[ref.relationship] = { data: merged };
+                }
+            }
+            const nextData = { ...data };
+            if (Object.keys(nextAttributes).length > 0)
+                nextData.attributes = nextAttributes;
+            else
+                delete nextData.attributes;
+            if (Object.keys(relationships).length > 0)
+                nextData.relationships = relationships;
+            return { ...req, body: JSON.stringify({ ...doc, data: nextData }) };
+        },
+    };
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@gaia-ai/addon-name-refs",
+  "version": "0.11.1",
+  "description": "GAIA connection addon: resolve entity NAMES (--label_names, --environment_names) into the relationships that reference them, on the live write, via dropsh's extendOperationSchema and alterRequest hooks.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/keytec/gaia.git",
+    "directory": "gaia-cli/addons/name-refs"
+  },
+  "dependencies": {
+    "dropsh": "^0.6.1"
+  },
+  "peerDependencies": {
+    "@gaia-ai/core": "^0.11.1"
+  }
+}