@infinisys/is-devops 0.0.0-stage → 0.1.1

package/lib/git-tool.js

@@ -0,0 +1,223 @@
+/**
+ * The `infinity_git` agent tool.
+ *
+ * One compact tool with read-only inspection (`status`, `diff`, `log`) and the
+ * three mutation steps that must stay auditable (`stage`, `commit`, `push`).
+ * It is the only supported way for Team Collaboration Mode Agents to touch
+ * Git: `is-fabric-team` denies direct Git invocations through `bash`.
+ */
+import { GitFoxError } from './gitfox-api.js';
+
+/** Model-facing description. */
+const TOOL_DESCRIPTION =
+  'Inspect and change the local Git repository behind the session workspace. Read actions: status, diff, log. Mutation actions: stage, unstage, switch, commit, fetch, rebase, rebase_continue, rebase_abort, push, delete_branch, prune_worktrees. Staging is recorded per seat: a commit contains exactly the paths this seat staged, so work staged by another seat and edits made after staging cannot ride along. "delete_branch" removes a local branch (never the checked-out one; remote branches go through infinity_devops) and "prune_worktrees" drops metadata for worktrees whose directory is gone. "switch" checks out a branch (create it with "create" and start it at "from"); uncommitted changes are carried across the switch, so never ask the user to run Git themselves. A rebase runs locally on the checked-out branch; when it stops on conflicts, resolve the listed files, stage them and call rebase_continue (or rebase_abort), then push. Commits are authored as infinsys-<role>; fetch and push authenticate to GitFox with the saved PAT/OAuth2 token and use the "namespace/name" project. No shell is involved and all paths must stay inside the workspace.';
+
+/** JSON-schema parameters of `infinity_git`. */
+const TOOL_PARAMETERS = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    action: {
+      type: 'string',
+      enum: [
+        'status',
+        'diff',
+        'log',
+        'stage',
+        'unstage',
+        'switch',
+        'commit',
+        'fetch',
+        'rebase',
+        'rebase_continue',
+        'rebase_abort',
+        'push',
+        'delete_branch',
+        'prune_worktrees',
+      ],
+      description: 'Git operation. Read actions are safe; mutation actions are audited.',
+    },
+    paths: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Workspace-relative paths: stage and unstage take the paths to add or drop, commit takes exactly the paths to include (the rest of this seat\'s staging stays for a later commit), diff and log take path filters. Never absolute and never .git.',
+    },
+    message: { type: 'string', description: 'Commit message for action "commit".' },
+    project: {
+      type: 'string',
+      description: 'GitFox project in "namespace/name" form; required for "push".',
+    },
+    branch: {
+      type: 'string',
+      description:
+        'Branch to check out, create or push; for "fetch" the branch to fetch, for "push" the remote branch (defaults to the current branch).',
+    },
+    create: {
+      type: 'boolean',
+      description: 'Create the branch during action "switch" instead of requiring it to exist.',
+    },
+    from: {
+      type: 'string',
+      description:
+        'Start point for a created branch ("origin/main", a tag, a SHA or a branch); defaults to the current HEAD.',
+    },
+    onto: {
+      type: 'string',
+      description:
+        'Commit-ish to rebase onto ("origin/main", a tag or a SHA). Omit to rebase onto the upstream of the checked-out branch.',
+    },
+    force: {
+      type: 'boolean',
+      description:
+        'Use --force-with-lease for "push", or force the deletion of an unmerged local branch for "delete_branch"; never allowed on main/master.',
+    },
+    staged: { type: 'boolean', description: 'Diff the index instead of the working tree.' },
+    stat: { type: 'boolean', description: 'Return a diffstat instead of a patch.' },
+    limit: {
+      type: 'integer',
+      minimum: 1,
+      maximum: 100,
+      description: 'Number of commits for "log"; defaults to 20.',
+    },
+  },
+  required: ['action'],
+};
+
+/**
+ * @param {unknown} value - canonical tool value.
+ * @returns {string} model-facing text bounded to 24k characters.
+ */
+function formatValue(value) {
+  const text = JSON.stringify(value, null, 2) ?? 'null';
+  return text.length <= 24_000 ? text : `${text.slice(0, 24_000)}\n… (truncated)`;
+}
+
+/**
+ * Resolve the repository root for one tool call.
+ *
+ * The header keeps the directory the session was opened with, so a worker that
+ * moved into a worktree still reports the project root there. The live
+ * directory (`workingDirectory` service) is what the call is actually running
+ * in, which is the repository a lane's commits belong to.
+ *
+ * @param {{ agent?: { session?: { header?: { cwd?: unknown } } } }} [exec] - execution context.
+ * @param {((agent: object) => string | null) | undefined} directoryOf - live directory accessor.
+ * @returns {string} absolute session workspace.
+ */
+function workspaceRootFor(exec, directoryOf) {
+  try {
+    const live = directoryOf?.(exec?.agent);
+    if (typeof live === 'string' && live !== '') return live;
+  } catch {
+    // A Host without the service, or one that cannot answer yet, keeps the header.
+  }
+  const cwd = exec?.agent?.session?.header?.cwd;
+  if (typeof cwd === 'string' && cwd !== '') return cwd;
+  return process.cwd();
+}
+
+/**
+ * Validate and shape one action before it reaches the repository service.
+ *
+ * @param {string} action - action name.
+ * @param {Record<string, any>} args - tool arguments.
+ * @returns {object} options for the repository service.
+ */
+function actionOptions(action, args) {
+  if (action === 'push' || action === 'fetch') {
+    if (typeof args.project !== 'string' || args.project.trim() === '') {
+      throw new GitFoxError(`action "${action}" requires "project"`, { code: 'invalid-arguments' });
+    }
+  }
+  if (action === 'commit' && (typeof args.message !== 'string' || args.message.trim() === '')) {
+    throw new GitFoxError('action "commit" requires "message"', { code: 'invalid-arguments' });
+  }
+  if (action === 'switch' && (typeof args.branch !== 'string' || args.branch.trim() === '')) {
+    throw new GitFoxError('action "switch" requires "branch"', { code: 'invalid-arguments' });
+  }
+  if (action === 'delete_branch' && (typeof args.branch !== 'string' || args.branch.trim() === '')) {
+    throw new GitFoxError('action "delete_branch" requires "branch"', { code: 'invalid-arguments' });
+  }
+  return {
+    project: args.project,
+    branch: args.branch,
+    create: args.create === true,
+    from: args.from,
+    force: args.force === true,
+    onto: args.onto,
+    message: args.message,
+    paths: args.paths,
+    staged: args.staged === true,
+    stat: args.stat === true,
+    limit: args.limit,
+  };
+}
+
+/**
+ * Run one action and return the canonical tool value.
+ *
+ * @param {object} git - repository service.
+ * @param {string} action - action name.
+ * @param {Record<string, any>} args - tool arguments.
+ * @param {{ workspaceRoot: string, signal?: AbortSignal, actor: object }} context - resolved invocation.
+ * @returns {Promise<object>} canonical result.
+ */
+async function executeAction(git, action, args, context) {
+  const options = { ...actionOptions(action, args), ...context };
+  if (typeof git[action] !== 'function') {
+    throw new Error(`invalid-arguments: unknown action "${action}"`);
+  }
+  try {
+    const result = await git[action](context.actor, options);
+    return action === 'push'
+      ? { action, project: args.project, result }
+      : { action, result };
+  } catch (error) {
+    if (error instanceof GitFoxError) {
+      throw new Error(`${error.code}: ${error.message}`, { cause: error });
+    }
+    throw error;
+  }
+}
+
+/**
+ * Build the `infinity_git` tool definition.
+ *
+ * @param {{ git: object, resolveActor: (agent?: object) => Promise<object> }} deps - wiring.
+ * @returns {object} tool definition.
+ */
+export function createGitTool({ git, resolveActor, directoryOf }) {
+  return {
+    name: 'infinity_git',
+    description: TOOL_DESCRIPTION,
+    parameters: TOOL_PARAMETERS,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      /**
+       * @param {unknown} _args - validated arguments.
+       * @param {unknown} value - canonical value.
+       * @returns {Array<{ type: 'text', text: string }>} model-facing content.
+       */
+      render(_args, value) {
+        return [{ type: 'text', text: formatValue(value) }];
+      },
+    },
+    /**
+     * @param {Record<string, any>} args - validated arguments.
+     * @param {{ signal?: AbortSignal, agent?: object }} exec - execution context.
+     * @returns {Promise<object>} canonical value.
+     */
+    async execute(args, exec) {
+      exec.signal?.throwIfAborted();
+      const actor = await resolveActor(exec.agent);
+      const result = await executeAction(git, args.action, args, {
+        workspaceRoot: workspaceRootFor(exec, directoryOf),
+        signal: exec.signal,
+        actor,
+      });
+      exec.signal?.throwIfAborted();
+      return result;
+    },
+  };
+}