teamshare-bridge 0.1.0 → 0.2.0

package/dist/lib/orchestrator/worktree.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWorktreeRoot = getWorktreeRoot;
+exports.createWorktree = createWorktree;
+exports.removeWorktree = removeWorktree;
+exports.gitStatus = gitStatus;
+exports.gitCommit = gitCommit;
+exports.gitMerge = gitMerge;
+exports.gitDiff = gitDiff;
+/**
+ * Git Worktree Manager: creates, manages, and removes Git worktrees
+ * for orchestrator tasks. All git operations use native CLI.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const log = {
+    info: (msg) => console.log(`[worktree] ${msg}`),
+    warn: (msg) => console.warn(`[worktree] ${msg}`),
+    error: (msg) => console.error(`[worktree] ${msg}`),
+};
+/**
+ * Validate that a path is safe (no traversal, no network drives).
+ * Returns true if the path is safe to use.
+ */
+function validatePath(p) {
+    const resolved = (0, path_1.resolve)(p);
+    // Block UNC paths (\\server\share)
+    if (resolved.startsWith('\\\\'))
+        return false;
+    // Block paths with ..
+    if (p.includes('..'))
+        return false;
+    // Block absolute paths that escape the user profile (basic check)
+    const home = process.env.USERPROFILE ?? process.env.HOME ?? '';
+    if (home && !resolved.startsWith(home) && !resolved.startsWith('/tmp')) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Get the worktree root directory for a project.
+ * Derived from the project's linked path.
+ */
+function getWorktreeRoot(projectPath) {
+    return (0, path_1.join)((0, path_1.resolve)(projectPath, '..'), '.teamshare-worktrees');
+}
+/**
+ * Create a new Git worktree for an orchestrator task.
+ */
+function createWorktree(repoPath, branch, baseBranch, taskId) {
+    // Validate paths
+    if (!validatePath(repoPath)) {
+        throw new Error(`Invalid repository path: ${repoPath}`);
+    }
+    const worktreeRoot = getWorktreeRoot(repoPath);
+    const worktreePath = (0, path_1.join)(worktreeRoot, `task-${taskId}`);
+    // Ensure worktree root exists
+    if (!(0, fs_1.existsSync)(worktreeRoot)) {
+        (0, fs_1.mkdirSync)(worktreeRoot, { recursive: true });
+    }
+    // Check if worktree already exists
+    if ((0, fs_1.existsSync)(worktreePath)) {
+        log.warn(`Worktree already exists at ${worktreePath}, removing`);
+        removeWorktree(repoPath, worktreePath);
+    }
+    // Create the worktree
+    try {
+        (0, child_process_1.execSync)(`git worktree add "${worktreePath}" -b ${branch} ${baseBranch}`, { cwd: repoPath, encoding: 'utf-8', timeout: 30_000 });
+    }
+    catch (err) {
+        // If branch already exists, try without -b
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('already exists')) {
+            (0, child_process_1.execSync)(`git worktree add "${worktreePath}" ${branch}`, { cwd: repoPath, encoding: 'utf-8', timeout: 30_000 });
+        }
+        else {
+            throw err;
+        }
+    }
+    // Get the current commit hash
+    const commitHash = (0, child_process_1.execSync)('git rev-parse HEAD', {
+        cwd: worktreePath,
+        encoding: 'utf-8',
+        timeout: 5_000,
+    }).trim();
+    log.info(`Created worktree at ${worktreePath} (branch: ${branch}, commit: ${commitHash})`);
+    return { path: worktreePath, branch, commitHash };
+}
+/**
+ * Remove a Git worktree.
+ */
+function removeWorktree(repoPath, worktreePath) {
+    try {
+        // Discard any uncommitted changes
+        (0, child_process_1.execSync)('git checkout -- .', {
+            cwd: worktreePath,
+            encoding: 'utf-8',
+            timeout: 10_000,
+        });
+        (0, child_process_1.execSync)('git clean -fd', {
+            cwd: worktreePath,
+            encoding: 'utf-8',
+            timeout: 10_000,
+        });
+        // Remove the worktree
+        (0, child_process_1.execSync)(`git worktree remove "${worktreePath}" --force`, {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            timeout: 30_000,
+        });
+        log.info(`Removed worktree at ${worktreePath}`);
+    }
+    catch (err) {
+        log.error(`Failed to remove worktree: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Get git status for a worktree.
+ */
+function gitStatus(worktreePath) {
+    try {
+        const branch = (0, child_process_1.execSync)('git branch --show-current', {
+            cwd: worktreePath,
+            encoding: 'utf-8',
+            timeout: 5_000,
+        }).trim();
+        const statusOutput = (0, child_process_1.execSync)('git status --porcelain', {
+            cwd: worktreePath,
+            encoding: 'utf-8',
+            timeout: 5_000,
+        });
+        const files = statusOutput
+            .split('\n')
+            .filter((line) => line.trim())
+            .map((line) => line.slice(3));
+        const aheadOutput = (0, child_process_1.execSync)('git rev-list --count HEAD @{u}..HEAD 2>/dev/null || echo 0', {
+            cwd: worktreePath,
+            encoding: 'utf-8',
+            timeout: 5_000,
+        }).trim();
+        return {
+            branch,
+            dirty: files.length > 0,
+            ahead: parseInt(aheadOutput, 10) || 0,
+            files,
+        };
+    }
+    catch (err) {
+        log.error(`git status failed: ${err instanceof Error ? err.message : String(err)}`);
+        return { branch: 'unknown', dirty: false, ahead: 0, files: [] };
+    }
+}
+/**
+ * Commit changes in a worktree.
+ */
+function gitCommit(worktreePath, message, files) {
+    try {
+        if (files && files.length > 0) {
+            (0, child_process_1.execSync)(`git add ${files.join(' ')}`, {
+                cwd: worktreePath,
+                encoding: 'utf-8',
+                timeout: 10_000,
+            });
+        }
+        else {
+            (0, child_process_1.execSync)('git add -A', {
+                cwd: worktreePath,
+                encoding: 'utf-8',
+                timeout: 10_000,
+            });
+        }
+        (0, child_process_1.execSync)(`git commit -m "${message}"`, {
+            cwd: worktreePath,
+            encoding: 'utf-8',
+            timeout: 10_000,
+        });
+        const hash = (0, child_process_1.execSync)('git rev-parse HEAD', {
+            cwd: worktreePath,
+            encoding: 'utf-8',
+            timeout: 5_000,
+        }).trim();
+        log.info(`Committed: ${hash} - ${message}`);
+        return hash;
+    }
+    catch (err) {
+        log.error(`git commit failed: ${err instanceof Error ? err.message : String(err)}`);
+        throw err;
+    }
+}
+/**
+ * Merge a branch into the integration branch.
+ */
+function gitMerge(repoPath, sourceBranch, targetBranch) {
+    try {
+        // Checkout target branch
+        (0, child_process_1.execSync)(`git checkout ${targetBranch}`, {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            timeout: 10_000,
+        });
+        // Merge source branch
+        (0, child_process_1.execSync)(`git merge ${sourceBranch} --no-edit`, {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            timeout: 30_000,
+        });
+        log.info(`Merged ${sourceBranch} into ${targetBranch}`);
+        return { success: true };
+    }
+    catch (err) {
+        // Check for merge conflicts
+        try {
+            const conflictOutput = (0, child_process_1.execSync)('git diff --name-only --diff-filter=U', {
+                cwd: repoPath,
+                encoding: 'utf-8',
+                timeout: 5_000,
+            });
+            const conflictFiles = conflictOutput.split('\n').filter((f) => f.trim());
+            return { success: false, conflictFiles };
+        }
+        catch {
+            return { success: false };
+        }
+    }
+}
+/**
+ * Get the diff for a worktree.
+ */
+function gitDiff(worktreePath) {
+    try {
+        return (0, child_process_1.execSync)('git diff --stat', {
+            cwd: worktreePath,
+            encoding: 'utf-8',
+            timeout: 10_000,
+        });
+    }
+    catch (err) {
+        log.error(`git diff failed: ${err instanceof Error ? err.message : String(err)}`);
+        return '';
+    }
+}
+//# sourceMappingURL=worktree.js.map

package/dist/lib/orchestrator/worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../../../src/lib/orchestrator/worktree.ts"],"names":[],"mappings":";;AAiDA,0CAEC;AAKD,wCAsDC;AAKD,wCA4BC;AAKD,8BAmCC;AAKD,8BAsCC;AAKD,4BAoCC;AAKD,0BAWC;AA3RD;;;GAGG;AACH,iDAAuD;AACvD,2BAA2C;AAC3C,+BAAqC;AAErC,MAAM,GAAG,GAAG;IACV,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,GAAG,EAAE,CAAC;IACvD,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,GAAG,EAAE,CAAC;IACxD,KAAK,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,GAAG,EAAE,CAAC;CAC3D,CAAC;AAeF;;;GAGG;AACH,SAAS,YAAY,CAAC,CAAS;IAC7B,MAAM,QAAQ,GAAG,IAAA,cAAO,EAAC,CAAC,CAAC,CAAC;IAC5B,mCAAmC;IACnC,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,sBAAsB;IACtB,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,kEAAkE;IAClE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;IAC/D,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACvE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe,CAAC,WAAmB;IACjD,OAAO,IAAA,WAAI,EAAC,IAAA,cAAO,EAAC,WAAW,EAAE,IAAI,CAAC,EAAE,sBAAsB,CAAC,CAAC;AAClE,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAC5B,QAAgB,EAChB,MAAc,EACd,UAAkB,EAClB,MAAc;IAEd,iBAAiB;IACjB,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,YAAY,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,IAAA,WAAI,EAAC,YAAY,EAAE,QAAQ,MAAM,EAAE,CAAC,CAAC;IAE1D,8BAA8B;IAC9B,IAAI,CAAC,IAAA,eAAU,EAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,IAAA,cAAS,EAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,mCAAmC;IACnC,IAAI,IAAA,eAAU,EAAC,YAAY,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,IAAI,CAAC,8BAA8B,YAAY,YAAY,CAAC,CAAC;QACjE,cAAc,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IACzC,CAAC;IAED,sBAAsB;IACtB,IAAI,CAAC;QACH,IAAA,wBAAQ,EACN,qBAAqB,YAAY,QAAQ,MAAM,IAAI,UAAU,EAAE,EAC/D,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CACtD,CAAC;IACJ,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,2CAA2C;QAC3C,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,IAAI,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACnC,IAAA,wBAAQ,EACN,qBAAqB,YAAY,KAAK,MAAM,EAAE,EAC9C,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CACtD,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,8BAA8B;IAC9B,MAAM,UAAU,GAAG,IAAA,wBAAQ,EAAC,oBAAoB,EAAE;QAChD,GAAG,EAAE,YAAY;QACjB,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,KAAK;KACf,CAAC,CAAC,IAAI,EAAE,CAAC;IAEV,GAAG,CAAC,IAAI,CAAC,uBAAuB,YAAY,aAAa,MAAM,aAAa,UAAU,GAAG,CAAC,CAAC;IAE3F,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAC5B,QAAgB,EAChB,YAAoB;IAEpB,IAAI,CAAC;QACH,kCAAkC;QAClC,IAAA,wBAAQ,EAAC,mBAAmB,EAAE;YAC5B,GAAG,EAAE,YAAY;YACjB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,MAAM;SAChB,CAAC,CAAC;QACH,IAAA,wBAAQ,EAAC,eAAe,EAAE;YACxB,GAAG,EAAE,YAAY;YACjB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,MAAM;SAChB,CAAC,CAAC;QAEH,sBAAsB;QACtB,IAAA,wBAAQ,EAAC,wBAAwB,YAAY,WAAW,EAAE;YACxD,GAAG,EAAE,QAAQ;YACb,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,MAAM;SAChB,CAAC,CAAC;QAEH,GAAG,CAAC,IAAI,CAAC,uBAAuB,YAAY,EAAE,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,GAAG,CAAC,KAAK,CAAC,8BAA8B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9F,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,SAAS,CAAC,YAAoB;IAC5C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAA,wBAAQ,EAAC,2BAA2B,EAAE;YACnD,GAAG,EAAE,YAAY;YACjB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,KAAK;SACf,CAAC,CAAC,IAAI,EAAE,CAAC;QAEV,MAAM,YAAY,GAAG,IAAA,wBAAQ,EAAC,wBAAwB,EAAE;YACtD,GAAG,EAAE,YAAY;YACjB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,KAAK;SACf,CAAC,CAAC;QAEH,MAAM,KAAK,GAAG,YAAY;aACvB,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;aAC7B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAEhC,MAAM,WAAW,GAAG,IAAA,wBAAQ,EAAC,4DAA4D,EAAE;YACzF,GAAG,EAAE,YAAY;YACjB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,KAAK;SACf,CAAC,CAAC,IAAI,EAAE,CAAC;QAEV,OAAO;YACL,MAAM;YACN,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC;YACvB,KAAK,EAAE,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,CAAC;YACrC,KAAK;SACN,CAAC;IACJ,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,GAAG,CAAC,KAAK,CAAC,sBAAsB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpF,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAClE,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,SAAS,CACvB,YAAoB,EACpB,OAAe,EACf,KAAgB;IAEhB,IAAI,CAAC;QACH,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,IAAA,wBAAQ,EAAC,WAAW,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE;gBACrC,GAAG,EAAE,YAAY;gBACjB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,MAAM;aAChB,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAA,wBAAQ,EAAC,YAAY,EAAE;gBACrB,GAAG,EAAE,YAAY;gBACjB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,MAAM;aAChB,CAAC,CAAC;QACL,CAAC;QAED,IAAA,wBAAQ,EAAC,kBAAkB,OAAO,GAAG,EAAE;YACrC,GAAG,EAAE,YAAY;YACjB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,MAAM;SAChB,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,IAAA,wBAAQ,EAAC,oBAAoB,EAAE;YAC1C,GAAG,EAAE,YAAY;YACjB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,KAAK;SACf,CAAC,CAAC,IAAI,EAAE,CAAC;QAEV,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,MAAM,OAAO,EAAE,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,GAAG,CAAC,KAAK,CAAC,sBAAsB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpF,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,QAAQ,CACtB,QAAgB,EAChB,YAAoB,EACpB,YAAoB;IAEpB,IAAI,CAAC;QACH,yBAAyB;QACzB,IAAA,wBAAQ,EAAC,gBAAgB,YAAY,EAAE,EAAE;YACvC,GAAG,EAAE,QAAQ;YACb,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,MAAM;SAChB,CAAC,CAAC;QAEH,sBAAsB;QACtB,IAAA,wBAAQ,EAAC,aAAa,YAAY,YAAY,EAAE;YAC9C,GAAG,EAAE,QAAQ;YACb,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,MAAM;SAChB,CAAC,CAAC;QAEH,GAAG,CAAC,IAAI,CAAC,UAAU,YAAY,SAAS,YAAY,EAAE,CAAC,CAAC;QACxD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,4BAA4B;QAC5B,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,IAAA,wBAAQ,EAAC,sCAAsC,EAAE;gBACtE,GAAG,EAAE,QAAQ;gBACb,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,KAAK;aACf,CAAC,CAAC;YACH,MAAM,aAAa,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACzE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,OAAO,CAAC,YAAoB;IAC1C,IAAI,CAAC;QACH,OAAO,IAAA,wBAAQ,EAAC,iBAAiB,EAAE;YACjC,GAAG,EAAE,YAAY;YACjB,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,MAAM;SAChB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,GAAG,CAAC,KAAK,CAAC,oBAAoB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClF,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/lib/session-stream.d.ts

@@ -8,7 +8,7 @@ export interface SessionMeta {
     agentId: string;
     projectId?: string;
     taskId?: string;
-    mode: 'run' | 'chat';
+    mode: 'run' | 'chat' | 'build';
     model?: string | null;
 }
 export declare function sessionsDir(): string;

package/dist/lib/skills.d.ts

@@ -0,0 +1,21 @@
+/** The three skills shipped with the bridge (source of truth: ./skills). */
+export declare const SHIPPED_SKILLS: readonly ["teamshare-cdd", "teamshare-modularity", "teamshare-auth-rbac"];
+/** Source: <package>/skills (ships in the npm tarball via package.json files). */
+export declare function skillsSourceDir(): string;
+/** Target: ~/.agents/skills (opencode convention) unless overridden. */
+export declare function skillsTargetDir(): string;
+export declare function listSkills(): {
+    available: string[];
+    installed: string[];
+    target: string;
+};
+/** Idempotently copies every shipped skill into the target skills directory. */
+export declare function installSkills(): {
+    copied: string[];
+    target: string;
+};
+/** Removes the shipped skills from the target directory (leaves others). */
+export declare function uninstallSkills(): {
+    removed: string[];
+    target: string;
+};

package/dist/lib/skills.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHIPPED_SKILLS = void 0;
+exports.skillsSourceDir = skillsSourceDir;
+exports.skillsTargetDir = skillsTargetDir;
+exports.listSkills = listSkills;
+exports.installSkills = installSkills;
+exports.uninstallSkills = uninstallSkills;
+/**
+ * TeamShare agent skills (IMP-603): ships the opencode skills that enforce
+ * documents-driven development, modular architecture and auth/RBAC inside
+ * TeamShare repos. The bridge installs them into the user's opencode skills
+ * directory (~/.agents/skills by default) so every harness session can load
+ * them via their SKILL.md frontmatter.
+ */
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** The three skills shipped with the bridge (source of truth: ./skills). */
+exports.SHIPPED_SKILLS = [
+    'teamshare-cdd',
+    'teamshare-modularity',
+    'teamshare-auth-rbac',
+];
+/** Source: <package>/skills (ships in the npm tarball via package.json files). */
+function skillsSourceDir() {
+    return (0, node_path_1.join)(__dirname, '..', '..', 'skills');
+}
+/** Target: ~/.agents/skills (opencode convention) unless overridden. */
+function skillsTargetDir() {
+    return process.env.TEAMSHARE_SKILLS_DIR ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.agents', 'skills');
+}
+function skillDirs(root) {
+    if (!(0, node_fs_1.existsSync)(root))
+        return [];
+    return (0, node_fs_1.readdirSync)(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && (0, node_fs_1.existsSync)((0, node_path_1.join)(root, entry.name, 'SKILL.md')))
+        .map((entry) => entry.name)
+        .sort();
+}
+function listSkills() {
+    return {
+        available: skillDirs(skillsSourceDir()),
+        installed: skillDirs(skillsTargetDir()),
+        target: skillsTargetDir(),
+    };
+}
+/** Idempotently copies every shipped skill into the target skills directory. */
+function installSkills() {
+    const source = skillsSourceDir();
+    if (!(0, node_fs_1.existsSync)(source)) {
+        throw new Error(`[skills] source not found in this installation: ${source} (skills ship with the npm package; running from a source checkout also works)`);
+    }
+    const target = skillsTargetDir();
+    (0, node_fs_1.mkdirSync)(target, { recursive: true });
+    const copied = [];
+    for (const name of skillDirs(source)) {
+        const dest = (0, node_path_1.join)(target, name);
+        (0, node_fs_1.mkdirSync)(dest, { recursive: true });
+        for (const file of (0, node_fs_1.readdirSync)((0, node_path_1.join)(source, name))) {
+            (0, node_fs_1.copyFileSync)((0, node_path_1.join)(source, name, file), (0, node_path_1.join)(dest, file));
+        }
+        copied.push(name);
+    }
+    return { copied, target };
+}
+/** Removes the shipped skills from the target directory (leaves others). */
+function uninstallSkills() {
+    const target = skillsTargetDir();
+    const removed = [];
+    for (const name of exports.SHIPPED_SKILLS) {
+        const dir = (0, node_path_1.join)(target, name);
+        if ((0, node_fs_1.existsSync)(dir)) {
+            (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+            removed.push(name);
+        }
+    }
+    return { removed, target };
+}
+//# sourceMappingURL=skills.js.map

package/dist/lib/skills.js.map

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

package/dist/lib/usage.d.ts

@@ -0,0 +1,52 @@
+export interface UsageSession {
+    title: string;
+    model: string;
+    providerID: string;
+    cost: number;
+    tokensInput: number;
+    tokensOutput: number;
+    tokensReasoning: number;
+    tokensCacheRead: number;
+    tokensCacheWrite: number;
+    timeCreated: number;
+    timeUpdated: number;
+    durationMin: number;
+    /** 'user' = the user's own opencode windows; 'agent' = agent sessions. */
+    attribution: 'user' | 'agent';
+    /** True when the title starts with "TeamShare " (bridge/TeamShare work). */
+    teamshare: boolean;
+}
+export interface UsageReport {
+    day: string;
+    dbPath: string;
+    totalCost: number;
+    sessionCount: number;
+    userCost: number;
+    agentCost: number;
+    teamshareCost: number;
+    tokens: {
+        input: number;
+        output: number;
+        reasoning: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    sessions: UsageSession[];
+}
+export interface UsageOptions {
+    /** YYYY-MM-DD (default: today, local time). */
+    day?: string;
+    /** Filter to sessions whose title carries `agent <id>`. */
+    agent?: string;
+}
+/** Resolves the python binary: TEAMSHARE_PYTHON > known 3.14 > PATH python. */
+export declare function pythonBinary(): string;
+/** Absolute path to tools/usage_report.py (package root, whatever the cwd). */
+export declare function usageScriptPath(): string;
+export declare class UsageError extends Error {
+}
+/**
+ * Runs the read-only spend report. Throws UsageError when the script or the
+ * db is unavailable (the caller decides how loudly to fail).
+ */
+export declare function runUsageReport(opts?: UsageOptions): UsageReport;

package/dist/lib/usage.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageError = void 0;
+exports.pythonBinary = pythonBinary;
+exports.usageScriptPath = usageScriptPath;
+exports.runUsageReport = runUsageReport;
+/**
+ * Agent spend reporting - typed wrapper around tools/usage_report.py.
+ *
+ * Node has no built-in sqlite, so the CLI (and the local-server /usage
+ * endpoint) shells out to the Python script, which opens opencode.db with a
+ * READ-ONLY sqlite uri. Never writes, never copies - the db is the source
+ * of truth. Works fully offline; needs neither the backend nor the daemon.
+ */
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+/** Python 3.14 on this machine - has sqlite3 in stdlib and pip (unlike the
+ * undocumented PATH python 3.11). env TEAMSHARE_PYTHON overrides. */
+const KNOWN_PYTHON = 'C:\\Users\\Dominion Banjo\\AppData\\Local\\Python\\bin\\python.exe';
+/** Resolves the python binary: TEAMSHARE_PYTHON > known 3.14 > PATH python. */
+function pythonBinary() {
+    if (process.env.TEAMSHARE_PYTHON)
+        return process.env.TEAMSHARE_PYTHON;
+    if ((0, node_fs_1.existsSync)(KNOWN_PYTHON))
+        return KNOWN_PYTHON;
+    return 'python';
+}
+/** Absolute path to tools/usage_report.py (package root, whatever the cwd). */
+function usageScriptPath() {
+    return (0, node_path_1.join)(__dirname, '..', '..', 'tools', 'usage_report.py');
+}
+class UsageError extends Error {
+}
+exports.UsageError = UsageError;
+/**
+ * Runs the read-only spend report. Throws UsageError when the script or the
+ * db is unavailable (the caller decides how loudly to fail).
+ */
+function runUsageReport(opts = {}) {
+    const script = usageScriptPath();
+    if (!(0, node_fs_1.existsSync)(script)) {
+        throw new UsageError(`usage script not found: ${script} (reinstall teamshare-bridge)`);
+    }
+    const args = [script, '--json'];
+    if (opts.day)
+        args.push('--day', opts.day);
+    if (opts.agent)
+        args.push('--agent', opts.agent);
+    const res = (0, node_child_process_1.spawnSync)(pythonBinary(), args, { encoding: 'utf8' });
+    if (res.error) {
+        throw new UsageError(`could not run ${pythonBinary()} - is Python installed? (${res.error.message})`);
+    }
+    if (res.status !== 0) {
+        const detail = (res.stderr || res.stdout || '').trim();
+        throw new UsageError(detail || `usage report failed with exit code ${res.status}`);
+    }
+    try {
+        const parsed = JSON.parse(res.stdout);
+        if (typeof parsed.totalCost !== 'number' || !Array.isArray(parsed.sessions)) {
+            throw new Error('unexpected report shape');
+        }
+        return parsed;
+    }
+    catch (err) {
+        throw new UsageError(`could not parse usage report output: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=usage.js.map

package/dist/lib/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/lib/usage.ts"],"names":[],"mappings":";;;AA6DA,oCAIC;AAGD,0CAEC;AAQD,wCA6BC;AA3GD;;;;;;;GAOG;AACH,qCAAqC;AACrC,2DAA+C;AAC/C,yCAAiC;AA8CjC;qEACqE;AACrE,MAAM,YAAY,GAAG,oEAAoE,CAAC;AAE1F,+EAA+E;AAC/E,SAAgB,YAAY;IAC1B,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IACtE,IAAI,IAAA,oBAAU,EAAC,YAAY,CAAC;QAAE,OAAO,YAAY,CAAC;IAClD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,+EAA+E;AAC/E,SAAgB,eAAe;IAC7B,OAAO,IAAA,gBAAI,EAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC;AACjE,CAAC;AAED,MAAa,UAAW,SAAQ,KAAK;CAAG;AAAxC,gCAAwC;AAExC;;;GAGG;AACH,SAAgB,cAAc,CAAC,OAAqB,EAAE;IACpD,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,IAAI,CAAC,IAAA,oBAAU,EAAC,MAAM,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,2BAA2B,MAAM,+BAA+B,CAAC,CAAC;IACzF,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAChC,IAAI,IAAI,CAAC,GAAG;QAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,IAAI,CAAC,KAAK;QAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,IAAA,8BAAS,EAAC,YAAY,EAAE,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAClE,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QACd,MAAM,IAAI,UAAU,CAClB,iBAAiB,YAAY,EAAE,4BAA4B,GAAG,CAAC,KAAK,CAAC,OAAO,GAAG,CAChF,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACvD,MAAM,IAAI,UAAU,CAAC,MAAM,IAAI,sCAAsC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAgB,CAAC;QACrD,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5E,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,UAAU,CAClB,wCAAwC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC3F,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamshare-bridge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Local bridge for TeamShare agents - CLI session runner, auto-wake WebSocket daemon, and teamshare:// protocol handler.",
   "type": "commonjs",
   "license": "MIT",
@@ -18,6 +18,8 @@
   },
   "files": [
     "dist",
+    "skills",
+    "tools",
     "README.md"
   ],
   "bin": {

package/skills/teamshare-auth-rbac/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: teamshare-auth-rbac
+description: TeamShare auth & authorization rules for every endpoint you write or change. Pick the correct guard stack (@Permissions for human-only, @Public + AgentsDualAuthGuard + @ApiKeyScopes for agent+human surfaces, @Public for truly public, ApiKeyGuard + canUseTool for MCP). Enforce capability + key scope + project access (never less than two layers). Use envelope + zod validation + UPPER_SNAKE error codes, and write AgentLog rows for every agent action.
+---
+
+# TeamShare Auth & Authorization (RBAC)
+
+Every endpoint in `teamshare-backend` must declare its access story. Use this
+decision table; never leave an endpoint with default guards and no metadata.
+
+## 1. Choose the guard stack
+
+| Who calls it | What to use on the route |
+|---|---|
+| Human JWT only (company/team/env-var/roles/webhooks/invitations/attachments) | Leave global guards, add `@Permissions('<entity>.<action>')` (e.g. `document.create`) |
+| Agents AND humans (tasks, comments, chat, documents, search, projects, agents self-service) | Class-level `@Public()` + `@UseGuards(AgentsDualAuthGuard)` + per-route `@ApiKeyScopes('<entity>:read' \| '<entity>:write')` |
+| Truly public (auth, verify, reset, billing webhook, run-token redeem) | `@Public()` only |
+| MCP tools (`/api/mcp`) | `ApiKeyGuard` + per-tool `canUseTool(capabilities, keyScopes, required)` |
+
+`AgentsDualAuthGuard` accepts `X-Api-Key` (enforces `@ApiKeyScopes`) OR a
+`Bearer` JWT. **Do not combine `@Permissions` with `AgentsDualAuthGuard` on the
+same route** — global RbacGuard runs before the route guard can set
+`request.user` for key callers. Dual-auth routes delegate access to the
+service layer.
+
+## 2. The three enforcement layers (never less than two)
+
+For every agent action: **capability** (`Agent.capabilities`) + **API-key
+scope** (`@ApiKeyScopes`, minted by `scopesForCapabilities`) + **project
+access** (`assertProjectAccess`). Never gate access on env vars.
+
+- MCP tool → `ctx.canUse('<capability>')` (capability + scope) then the shared
+  service runs `assertProjectAccess` as the agent user.
+- Agent REST → `@ApiKeyScopes` (scope) then the service runs
+  `assertProjectAccess` (project role).
+- Service layer helpers: `assertProjectAccess(prisma, projectId, userId,
+  minRole)`, `assertCompanyMembership`, `isCompanyOwnerOrAdmin`.
+
+## 3. Permission vocabulary (CRUDL)
+
+- `src/common/constants/rbac.ts`: `ENTITIES` (17) × `ACTIONS`
+  (`create | read | list | update | delete`) → `Permission = entity.action`
+  plus `SPECIAL_PERMISSIONS` (`env_var.reveal`, `env_var.export`, ...).
+- Static role matrices: `COMPANY_ROLE_PERMISSIONS`
+  (owner/admin/member/secret_manager/viewer) and `PROJECT_ROLE_PERMISSIONS`
+  (owner/member/viewer). Dynamic roles add `companyPermissions` claims.
+- Agent capabilities live in `src/common/constants/enums.ts`
+  (`AGENT_CAPABILITIES`, `CAPABILITY_SCOPES`). A key never exceeds its
+  agent's capabilities and a capability never exceeds the key's scopes.
+- Add a new capability → add its scope in `API_KEY_SCOPES` + a mapping in
+  `CAPABILITY_SCOPES`, so `scopesForCapabilities` mints the right key.
+
+## 4. Error codes & envelope
+
+- Throw `new XxxException({ code: 'UPPER_SNAKE', message, details? })`
+  (`VALIDATION_ERROR`, `PROJECT_NOT_FOUND`, `INSUFFICIENT_PROJECT_ROLE`,
+  `API_KEY_SCOPE_MISSING`, `DOCUMENT_UPDATE_DENIED`, ...). Secrets never
+  appear in messages/logs.
+- Responses: `{ success: true, data, pagination? }` /
+  `{ success: false, error: { code, message, details? } }` (global
+  interceptor/filter — your handler returns raw data).
+
+## 5. AgentLog — never bypass
+
+Every agent mutation logs an `AgentLog` row via the shared services:
+`logAgentActionIfAgent(prisma, userId, { action, taskId?, detail })`
+(best-effort; humans skipped). Actions are in `AGENT_LOG_ACTIONS`
+(`task_created`, `comment_created`, `document_created`, `document_updated`,
+`subtask_updated`, `wake_sent`, ...). If you add an agent-facing mutation,
+wire the log in the service — never in the controller.
+
+## 6. Checklist for a new endpoint
+
+- [ ] Guard stack chosen from the table; metadata declared on the route.
+- [ ] zod `ZodValidationPipe` on body/query/param; generated zod for enums.
+- [ ] Service re-checks project/company access (guards are a first filter).
+- [ ] Envelope-compliant return; UPPER_SNAKE error codes.
+- [ ] Agent actions write `AgentLog` via `logAgentActionIfAgent`.
+- [ ] Swagger `@ApiOperation` mentions the RBAC; `@errs(...)` lists the codes.