@bakers-build/addon-workspace 0.0.0-stage → 0.1.0-next.42

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

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @bakers-build/addon-workspace
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+bakers.build connection addon: fills the ambient workspace (bb_workspace) into a create payload transparently, via dropsh's alterRequest hook.
+
+Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://git.key-tec.de/bakers-build/bakers-build (bakers-cli/).

package/dist/src/index.d.ts

@@ -0,0 +1,82 @@
+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.
+ *
+ * `bb_project` and `bb_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 `BbWorkspaceScope` gates the write;
+ * guessing one here would be inventing data, not supplying context.
+ *
+ * `bb_term` joined in BB-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: `@bakers-build/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[];
+/**
+ * Entity type → the JSON:API field path from it to the `bb_workspace` uuid.
+ *
+ * This is a SECOND list beside DEFAULT_WORKSPACE_ENTITY_TYPES and not an
+ * extension of it, because the two answer different questions. That one asks
+ * "is the workspace an ambient fact on a create?" and excludes bb_project and
+ * bb_ticket precisely because choosing their group/project is the caller's
+ * decision. This one asks "how is this type reachable from a workspace?", and
+ * for those two the answer exists — it is just longer.
+ *
+ * `bb_workspace` itself is deliberately ABSENT (BB-472 live verification):
+ * a `bb_workspace` collection search is exactly how `discoverBbWorkspaces()`
+ * lists what an identity can switch to, and narrowing it to
+ * `id = <the already-configured workspace>` would make every reachable
+ * workspace but the current one invisible — defeating the switch this ticket
+ * builds. Server-side membership (F2) already bounds that collection to what
+ * the identity may see; this client-side layer answers "which one is
+ * configured for creates/other reads", a question that does not apply to the
+ * workspace list itself.
+ */
+export declare const WORKSPACE_READ_SCOPE_PATHS: Readonly<Record<string, string | readonly string[]>>;
+/**
+ * BB-495 D5: every UI collection read that is NOT workspace-scoped by
+ * {@link WORKSPACE_READ_SCOPE_PATHS} and is, deliberately, not a gap to close
+ * here — closing one would be its own behaviour change and its own scope. The
+ * completeness gate (`addons/bakers-ui/tests/workspace-scope-coverage.test.ts`)
+ * derives every collection the UI reads from its source tree and fails on any
+ * that is neither covered above nor named here, so a new unscoped read is
+ * caught rather than silently added to an ever-growing exception list.
+ */
+export declare const UI_COLLECTION_EXCEPTIONS: readonly string[];
+/** Options for the workspace addon — normally the connection config's globals. */
+export interface WorkspaceOptions {
+    /**
+     * The UUID of the `bb_workspace` every create is bound to. REQUIRED at the
+     * top level of the connection config; `loadBbConfig` 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 bakers.build workspace plugin. Constructed by the `./preset` accumulator from the
+ * connection config's global options (via `@bakers-build/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,208 @@
+/**
+ * The entity types whose workspace is a DIRECT `workspace_id` field, and which
+ * this addon may therefore fill from context.
+ *
+ * `bb_project` and `bb_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 `BbWorkspaceScope` gates the write;
+ * guessing one here would be inventing data, not supplying context.
+ *
+ * `bb_term` joined in BB-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: `@bakers-build/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 = [
+    'bb_group',
+    'bb_team',
+    'bb_term',
+];
+/**
+ * Entity type → the JSON:API field path from it to the `bb_workspace` uuid.
+ *
+ * This is a SECOND list beside DEFAULT_WORKSPACE_ENTITY_TYPES and not an
+ * extension of it, because the two answer different questions. That one asks
+ * "is the workspace an ambient fact on a create?" and excludes bb_project and
+ * bb_ticket precisely because choosing their group/project is the caller's
+ * decision. This one asks "how is this type reachable from a workspace?", and
+ * for those two the answer exists — it is just longer.
+ *
+ * `bb_workspace` itself is deliberately ABSENT (BB-472 live verification):
+ * a `bb_workspace` collection search is exactly how `discoverBbWorkspaces()`
+ * lists what an identity can switch to, and narrowing it to
+ * `id = <the already-configured workspace>` would make every reachable
+ * workspace but the current one invisible — defeating the switch this ticket
+ * builds. Server-side membership (F2) already bounds that collection to what
+ * the identity may see; this client-side layer answers "which one is
+ * configured for creates/other reads", a question that does not apply to the
+ * workspace list itself.
+ */
+export const WORKSPACE_READ_SCOPE_PATHS = {
+    bb_group: 'workspace_id.id',
+    bb_team: 'workspace_id.id',
+    // bb_machine is account-owned: it has no workspace_id, and
+    // machineCapacity() must not send one. Isolation is owner_user_id on the
+    // server, not this client filter.
+    bb_term: 'workspace_id.id',
+    bb_project: 'group_id.workspace_id.id',
+    bb_ticket: 'project_id.group_id.workspace_id.id',
+    bb_environment: 'project_id.group_id.workspace_id.id',
+    bb_conductor: 'project_id.group_id.workspace_id.id',
+    // Exactly one of project and workspace is set on a template: either path
+    // admits it (an OR group).
+    bb_ticket_template: [
+        'project_id.group_id.workspace_id.id',
+        'workspace_id.id',
+    ],
+    bb_run: 'ticket_id.project_id.group_id.workspace_id.id',
+    bb_comment: 'ticket_id.project_id.group_id.workspace_id.id',
+};
+/**
+ * BB-495 D5: every UI collection read that is NOT workspace-scoped by
+ * {@link WORKSPACE_READ_SCOPE_PATHS} and is, deliberately, not a gap to close
+ * here — closing one would be its own behaviour change and its own scope. The
+ * completeness gate (`addons/bakers-ui/tests/workspace-scope-coverage.test.ts`)
+ * derives every collection the UI reads from its source tree and fails on any
+ * that is neither covered above nor named here, so a new unscoped read is
+ * caught rather than silently added to an ever-growing exception list.
+ */
+export const UI_COLLECTION_EXCEPTIONS = [
+    // `user` is not a bakers.build entity type — `WorkspaceReadScopeSubscriber`
+    // registers nothing for it (it hangs off `entity.query_access.<type>` for
+    // bakers.build types only), so `WORKSPACE_READ_SCOPE_PATHS` cannot list it either.
+    'user',
+    // A bespoke resource, not an entity query — `Entity/user/Data/users.ts:41`
+    // already called it "unscoped statistics" before this gate existed.
+    'bakers/statistics',
+    // OG core's own membership resource, not a bakers.build entity type either — the
+    // same class of gap as `user`, for the same subscriber-registration reason.
+    'og_membership',
+    // Deliberately never scoped, not merely unregistered: `bb_workspace`
+    // itself IS the reachable-workspace list — narrowing it to the already-
+    // configured workspace would make every workspace but the current one
+    // invisible, defeating the picker/switch this collection exists for.
+    // Server-side membership already bounds it to what the identity may see.
+    'bb_workspace',
+    // A bespoke resource keyed by ONE ticket's UUID, gated on view access to that
+    // ticket — the ticket already sits in the workspace it belongs to, so there
+    // is no collection to narrow.
+    'bakers/addons/ticket',
+];
+/** The filter group name. Unique by construction, so a caller filter cannot collide. */
+const READ_SCOPE_FILTER = 'bb_ambient_workspace';
+/** The JSON:API resource type of the workspace a `workspace_id` names. */
+const WORKSPACE_RESOURCE_TYPE = 'bb_workspace--bb_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 bakers.build workspace plugin. Constructed by the `./preset` accumulator from the
+ * connection config's global options (via `@bakers-build/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: 'bakers-workspace',
+        requiredModules: [],
+        async alterRequest(req, ctx) {
+            // Reads: narrow a COLLECTION to the configured workspace. `read` (an
+            // individual resource by uuid) is deliberately absent — JSON:API ignores
+            // filters on individual endpoints, so appending one there would be code that
+            // lies about what it does. Isolation on that path stays the server's.
+            if (ctx.operation === 'search') {
+                const path = ctx.entityType
+                    ? WORKSPACE_READ_SCOPE_PATHS[ctx.entityType]
+                    : undefined;
+                if (workspaceId === '' || path === undefined)
+                    return req;
+                const url = new URL(req.url);
+                const condition = (name, conditionPath) => {
+                    url.searchParams.set(`filter[${name}][condition][path]`, conditionPath);
+                    url.searchParams.set(`filter[${name}][condition][operator]`, '=');
+                    url.searchParams.set(`filter[${name}][condition][value]`, workspaceId);
+                };
+                if (typeof path === 'string') {
+                    condition(READ_SCOPE_FILTER, path);
+                }
+                else {
+                    url.searchParams.set(`filter[${READ_SCOPE_FILTER}][group][conjunction]`, 'OR');
+                    path.forEach((alternative, i) => {
+                        condition(`${READ_SCOPE_FILTER}_${i}`, alternative);
+                        url.searchParams.set(`filter[${READ_SCOPE_FILTER}_${i}][condition][memberOf]`, READ_SCOPE_FILTER);
+                    });
+                }
+                return { ...req, url: url.toString() };
+            }
+            // (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 `bakers-workspace`. Normally
+            // unreachable: `workspace_id` is required at config load.
+            if (workspaceId === '') {
+                throw new WorkspaceConfigError(`@bakers-build/addon-workspace: creating a "${ctx.entityType}" needs an ambient workspace, but none is configured. ` +
+                    `Set the top-level \`${WORKSPACE_FIELD}: '<bb_workspace uuid>'\` in your connection config (.bakers/bakers.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(`@bakers-build/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 { BbPreset } from '@bakers-build/core';
+import { type WorkspaceOptions } from './index.js';
+export declare const connectionPlugins: BbPreset<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

@@ -1,6 +1,28 @@
 {
   "name": "@bakers-build/addon-workspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-next.42",
+  "description": "bakers.build connection addon: fills the ambient workspace (bb_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/bakers-build/bakers-build.git",
+    "directory": "bakers-cli/addons/workspace"
+  },
+  "dependencies": {
+    "dropsh": "^0.7.5"
+  },
+  "peerDependencies": {
+    "@bakers-build/core": "^0.1.0-next.42"
+  }
+}