@gaia-ai/addon-workspace 0.11.0

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-workspace
+
+GAIA connection addon: fills the ambient workspace (gaia_workspace) into a create payload transparently, via dropsh's alterRequest hook.
+
+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,51 @@
+import type { DropSHPlugin } from 'dropsh/plugin';
+/**
+ * The entity types whose workspace is a DIRECT `workspace_id` field, and which
+ * this addon may therefore fill from context.
+ *
+ * `gaia_project` and `gaia_ticket` are deliberately ABSENT. Their workspace
+ * anchor is `group_id` / `project_id` — a genuine choice the caller must make
+ * (which group? which project?), not an ambient fact. The server narrows the
+ * offer for those two (`GroupInActiveWorkspaceSelection` /
+ * `ProjectInActiveWorkspaceSelection`) and `GaiaWorkspaceScope` gates the write;
+ * guessing one here would be inventing data, not supplying context.
+ *
+ * `gaia_term` joined in GAIA-339. It meets the criterion exactly — a direct
+ * `workspace_id`, and which workspace a label belongs to is ambient rather than
+ * chosen — and it is not merely a convenience: `@gaia/qualify-ticket` creates a
+ * missing `work:*` term through dropsh, so without this entry that step answers
+ * 422 on `workspace_id` on every instance where the term is not seeded yet.
+ */
+export declare const DEFAULT_WORKSPACE_ENTITY_TYPES: readonly string[];
+/** Options for the workspace addon — normally the connection config's globals. */
+export interface WorkspaceOptions {
+    /**
+     * The UUID of the `gaia_workspace` every create is bound to. REQUIRED at the
+     * top level of the connection config; `loadGaiaConfig` rejects a config
+     * without it, so by the time this addon runs the value is present.
+     */
+    workspace_id?: string;
+    /**
+     * Override the entity types whose `workspace_id` is filled from context.
+     * Defaults to `DEFAULT_WORKSPACE_ENTITY_TYPES`; configurable so a site that
+     * adds a further directly-bound type does not need a new addon release.
+     */
+    entity_types?: string[];
+}
+/** No workspace configured, but a create needed one. Named so `PluginError` reads. */
+export declare class WorkspaceConfigError extends Error {
+    readonly name = "WorkspaceConfigError";
+}
+/** The create body was not parseable JSON — fail loudly, never half-parse. */
+export declare class WorkspacePayloadError extends Error {
+    readonly name = "WorkspacePayloadError";
+}
+/**
+ * The GAIA workspace plugin. Constructed by the `./preset` accumulator from the
+ * connection config's global options (via `@gaia-ai/addon-essentials`, which
+ * lists this addon as a preset child), or directly by dropsh from a legacy
+ * `plugins: []` descriptor (this module default-exports the factory, so no
+ * `export:` is needed either way).
+ */
+export declare function workspacePlugin(opts?: WorkspaceOptions): DropSHPlugin;
+export default workspacePlugin;

package/dist/src/index.js

@@ -0,0 +1,107 @@
+/**
+ * The entity types whose workspace is a DIRECT `workspace_id` field, and which
+ * this addon may therefore fill from context.
+ *
+ * `gaia_project` and `gaia_ticket` are deliberately ABSENT. Their workspace
+ * anchor is `group_id` / `project_id` — a genuine choice the caller must make
+ * (which group? which project?), not an ambient fact. The server narrows the
+ * offer for those two (`GroupInActiveWorkspaceSelection` /
+ * `ProjectInActiveWorkspaceSelection`) and `GaiaWorkspaceScope` gates the write;
+ * guessing one here would be inventing data, not supplying context.
+ *
+ * `gaia_term` joined in GAIA-339. It meets the criterion exactly — a direct
+ * `workspace_id`, and which workspace a label belongs to is ambient rather than
+ * chosen — and it is not merely a convenience: `@gaia/qualify-ticket` creates a
+ * missing `work:*` term through dropsh, so without this entry that step answers
+ * 422 on `workspace_id` on every instance where the term is not seeded yet.
+ */
+export const DEFAULT_WORKSPACE_ENTITY_TYPES = [
+    'gaia_group',
+    'gaia_team',
+    'gaia_term',
+];
+/** The JSON:API resource type of the workspace a `workspace_id` names. */
+const WORKSPACE_RESOURCE_TYPE = 'gaia_workspace--gaia_workspace';
+/** The relationship this addon fills. */
+const WORKSPACE_FIELD = 'workspace_id';
+/** No workspace configured, but a create needed one. Named so `PluginError` reads. */
+export class WorkspaceConfigError extends Error {
+    name = 'WorkspaceConfigError';
+}
+/** The create body was not parseable JSON — fail loudly, never half-parse. */
+export class WorkspacePayloadError extends Error {
+    name = 'WorkspacePayloadError';
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * The GAIA workspace plugin. Constructed by the `./preset` accumulator from the
+ * connection config's global options (via `@gaia-ai/addon-essentials`, which
+ * lists this addon as a preset child), or directly by dropsh from a legacy
+ * `plugins: []` descriptor (this module default-exports the factory, so no
+ * `export:` is needed either way).
+ */
+export function workspacePlugin(opts = {}) {
+    const workspaceId = typeof opts.workspace_id === 'string' ? opts.workspace_id.trim() : '';
+    const entityTypes = new Set(opts.entity_types ?? [...DEFAULT_WORKSPACE_ENTITY_TYPES]);
+    return {
+        id: 'gaia-workspace',
+        requiredModules: [],
+        async alterRequest(req, ctx) {
+            // (1) Creates only. An `update` that re-binds an existing row to another
+            // workspace is a real decision governed by the server's own rule — never
+            // something to slip in ambiently — so PATCH is passed through untouched.
+            if (ctx.operation !== 'create')
+                return req;
+            // (2) Only the types whose workspace is a direct `workspace_id` field.
+            if (ctx.entityType === undefined || !entityTypes.has(ctx.entityType)) {
+                return req;
+            }
+            // (3) `upload` bodies are binary; nothing to parse.
+            if (typeof req.body !== 'string')
+                return req;
+            // (6) A create that needs a workspace with none configured must not go out
+            // unbound — the server would answer 422 and the cause would be invisible.
+            // dropsh wraps this in a PluginError carrying `gaia-workspace`. Normally
+            // unreachable: `workspace_id` is required at config load.
+            if (workspaceId === '') {
+                throw new WorkspaceConfigError(`@gaia-ai/addon-workspace: creating a "${ctx.entityType}" needs an ambient workspace, but none is configured. ` +
+                    `Set the top-level \`${WORKSPACE_FIELD}: '<gaia_workspace uuid>'\` in your connection config (.gaia/gaia.config.js).`);
+            }
+            // (7) Malformed JSON must fail by name, never be swallowed into a request
+            // that is half-rewritten.
+            let doc;
+            try {
+                doc = JSON.parse(req.body);
+            }
+            catch (cause) {
+                throw new WorkspacePayloadError(`@gaia-ai/addon-workspace: the "${ctx.entityType}" create body is not valid JSON, so the ambient workspace could not be applied: ${String(cause)}`);
+            }
+            if (!isRecord(doc) || !isRecord(doc.data))
+                return req;
+            const relationships = isRecord(doc.data.relationships)
+                ? doc.data.relationships
+                : undefined;
+            // (4) An explicit value ALWAYS wins over the ambient one.
+            if (relationships && WORKSPACE_FIELD in relationships)
+                return req;
+            // (5) Inject. Headers are untouched by construction — only `body` is
+            // replaced, so `Authorization` (applied before this hook) survives verbatim.
+            const next = {
+                ...doc,
+                data: {
+                    ...doc.data,
+                    relationships: {
+                        ...(relationships ?? {}),
+                        [WORKSPACE_FIELD]: {
+                            data: { type: WORKSPACE_RESOURCE_TYPE, id: workspaceId },
+                        },
+                    },
+                },
+            };
+            return { ...req, body: JSON.stringify(next) };
+        },
+    };
+}
+export default workspacePlugin;

package/dist/src/preset.d.ts

@@ -0,0 +1,3 @@
+import type { GaiaPreset } from '@gaia-ai/core';
+import { type WorkspaceOptions } from './index.js';
+export declare const connectionPlugins: GaiaPreset<WorkspaceOptions>['connectionPlugins'];

package/dist/src/preset.js

@@ -0,0 +1,8 @@
+import { workspacePlugin } from './index.js';
+export const connectionPlugins = (acc, opts) => {
+    const o = (opts ?? {});
+    if (typeof o.workspace_id !== 'string' || o.workspace_id.trim() === '') {
+        return acc;
+    }
+    return [...acc, workspacePlugin(o)];
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@gaia-ai/addon-workspace",
+  "version": "0.11.0",
+  "description": "GAIA connection addon: fills the ambient workspace (gaia_workspace) into a create payload transparently, via dropsh's alterRequest hook.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./preset": "./dist/src/preset.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/keytec/gaia.git",
+    "directory": "gaia-cli/addons/workspace"
+  },
+  "dependencies": {
+    "dropsh": "^0.6.1"
+  },
+  "peerDependencies": {
+    "@gaia-ai/core": "^0.11.0"
+  }
+}