@gaia-ai/addon-workspace-git 0.6.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-workspace-git
+
+GAIA conductor workspace addon: plain git-worktree workspace + the WORKFLOW.md instruction loader.
+
+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,38 @@
+import type { EnsuredWorkspace, GaiaWorkspace, WorkspacePlugin } from '@gaia-ai/conductor/contract';
+export { loadInstructions } from './instructions.js';
+/** Default branch template: `<prefix><key>-<title-slug>` (readable). */
+export declare const DEFAULT_BRANCH_TEMPLATE = "{branchPrefix}{key}-{titleSlug}";
+export type GitRunner = (args: string[], cwd: string) => Promise<void>;
+export interface GitWorkspaceOptions {
+    /** Main clone (a git repo): config source + worktree base. */
+    root: string;
+    /** Where per-ticket worktrees live. Default: `${root}-worktrees`. */
+    worktreesRoot?: string;
+    /** Branch name prefix per ticket. Default: 'gaia/'. */
+    branchPrefix?: string;
+    /**
+     * Branch name template. Vars: {branchPrefix}, {key} (sanitized identifier),
+     * {identifier}, {titleSlug}. Default: `{branchPrefix}{key}-{titleSlug}`.
+     */
+    branchTemplate?: string;
+    runGit?: GitRunner;
+}
+export declare class GitWorkspace implements GaiaWorkspace {
+    private readonly runGit;
+    private readonly root;
+    private readonly worktreesRoot;
+    private readonly branchPrefix;
+    private readonly branchTemplate;
+    constructor(options: GitWorkspaceOptions);
+    /** Render the branch name for a ticket from the configured template. */
+    branchFor(identifier: string, title?: string): string;
+    keyFor(identifier: string): string;
+    private pathFor;
+    ensure(identifier: string, title?: string, _baseRef?: string): Promise<EnsuredWorkspace>;
+    remove(identifier: string): Promise<void>;
+}
+export declare function gitWorkspace(opts?: {
+    branchPrefix?: string;
+    branchTemplate?: string;
+}): WorkspacePlugin;
+export default gitWorkspace;

package/dist/src/index.js

@@ -0,0 +1,95 @@
+// GAIA-224 (Finding 6, decisions 8 + 10): the plain git-worktree workspace —
+// formerly `@gaia-ai/core`'s `plugins/workspace/git.ts` — now its own
+// conductor-surface addon, which ALSO owns `loadInstructions` (the WORKFLOW.md
+// loader that used to be a core util). `@gaia-ai/addon-herdr` depends on this
+// package for it: the one addon→addon edge the layered acyclic rule permits.
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { exec, slugify } from '@gaia-ai/core';
+import { loadInstructions } from './instructions.js';
+export { loadInstructions } from './instructions.js';
+/** Default branch template: `<prefix><key>-<title-slug>` (readable). */
+export const DEFAULT_BRANCH_TEMPLATE = '{branchPrefix}{key}-{titleSlug}';
+function renderBranchTemplate(template, vars) {
+    const rendered = template.replace(/\{(\w+)\}/g, (whole, key) => {
+        const value = vars[key];
+        return value === undefined ? whole : value;
+    });
+    // An empty title slug leaves a dangling separator (e.g. `gaia/GL-9-`) —
+    // trim trailing branch separators so the branch stays a valid, tidy ref.
+    return rendered.replace(/[-_./]+$/g, '');
+}
+const defaultGitRunner = async (args, cwd) => {
+    await exec('git', args, { cwd });
+};
+export class GitWorkspace {
+    runGit;
+    root;
+    worktreesRoot;
+    branchPrefix;
+    branchTemplate;
+    constructor(options) {
+        this.runGit = options.runGit ?? defaultGitRunner;
+        this.root = resolve(options.root);
+        this.worktreesRoot = options.worktreesRoot
+            ? resolve(options.worktreesRoot)
+            : `${this.root}-worktrees`;
+        this.branchPrefix = options.branchPrefix ?? 'gaia/';
+        this.branchTemplate = options.branchTemplate ?? DEFAULT_BRANCH_TEMPLATE;
+    }
+    /** Render the branch name for a ticket from the configured template. */
+    branchFor(identifier, title) {
+        return renderBranchTemplate(this.branchTemplate, {
+            branchPrefix: this.branchPrefix,
+            key: this.keyFor(identifier),
+            identifier,
+            titleSlug: slugify(title ?? ''),
+        });
+    }
+    keyFor(identifier) {
+        return identifier.replace(/[^A-Za-z0-9._-]/g, '_');
+    }
+    pathFor(key) {
+        return resolve(join(this.worktreesRoot, key));
+    }
+    async ensure(identifier, title, _baseRef) {
+        const key = this.keyFor(identifier);
+        // Reject empty and dot-leading keys: a dot-leading key would produce an
+        // invalid git ref (e.g. `gaia/.hidden`) and covers '.'/'..' too.
+        if (key === '' || key.startsWith('.')) {
+            throw new Error(`invalid workspace identifier: ${identifier}`);
+        }
+        const path = this.pathFor(key);
+        if (existsSync(path)) {
+            return { path, instructions: loadInstructions(path), created: false };
+        }
+        const branch = this.branchFor(identifier, title);
+        await this.runGit(['-C', this.root, 'worktree', 'add', '--force', '-B', branch, path], this.root);
+        // The `after_create` hook is run by the executor (GAIA-84), not here — the
+        // workspace only reports that it created a fresh worktree.
+        return { path, instructions: loadInstructions(path), created: true };
+    }
+    async remove(identifier) {
+        const key = this.keyFor(identifier);
+        const path = this.pathFor(key);
+        await this.runGit(['-C', this.root, 'worktree', 'remove', '--force', path], this.root);
+    }
+}
+export function gitWorkspace(opts = {}) {
+    return {
+        kind: 'workspace',
+        id: 'git',
+        requiredModules: [],
+        async createWorkspace(config) {
+            const root = config.config_path
+                ? dirname(config.config_path)
+                : process.cwd();
+            return new GitWorkspace({
+                root,
+                ...(opts.branchPrefix ? { branchPrefix: opts.branchPrefix } : {}),
+                ...(opts.branchTemplate ? { branchTemplate: opts.branchTemplate } : {}),
+            });
+        },
+    };
+}
+export default gitWorkspace;

package/dist/src/instructions.d.ts

@@ -0,0 +1,6 @@
+/** Loads ./WORKFLOW.md from the workspace, hashing its content. */
+export declare function loadInstructions(workspacePath: string): {
+    path: string;
+    sha256: string;
+    text: string;
+} | null;

package/dist/src/instructions.js

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/** Loads ./WORKFLOW.md from the workspace, hashing its content. */
+export function loadInstructions(workspacePath) {
+    const path = resolve(workspacePath, 'WORKFLOW.md');
+    if (!existsSync(path)) {
+        return null;
+    }
+    const text = readFileSync(path, 'utf8');
+    return {
+        path,
+        sha256: createHash('sha256').update(text).digest('hex'),
+        text,
+    };
+}

package/dist/src/preset.d.ts

@@ -0,0 +1,2 @@
+import type { Preset } from '@gaia-ai/conductor/contract';
+export declare const workspaces: Preset['workspaces'];

package/dist/src/preset.js

@@ -0,0 +1,5 @@
+import { gitWorkspace } from './index.js';
+export const workspaces = (acc, opts) => [
+    ...acc,
+    gitWorkspace(opts),
+];

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@gaia-ai/addon-workspace-git",
+  "version": "0.6.1",
+  "description": "GAIA conductor workspace addon: plain git-worktree workspace + the WORKFLOW.md instruction loader.",
+  "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-git"
+  },
+  "peerDependencies": {
+    "@gaia-ai/conductor": "^0.6.1",
+    "@gaia-ai/core": "^0.6.1"
+  }
+}