@xn-intenton-z2a/agentic-lib 7.1.6

package/src/actions/agentic-step/tasks/resolve-issue.js

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tasks/resolve-issue.js — Issue → code → PR
+//
+// Given an issue number, reads the issue, generates code using the Copilot SDK,
+// validates with tests, and creates a PR.
+
+import * as core from "@actions/core";
+import { checkAttemptLimit, checkWipLimit, isIssueResolved } from "../safety.js";
+import { runCopilotTask, readOptionalFile, formatPathsSection } from "../copilot.js";
+
+/**
+ * Resolve a GitHub issue by generating code and creating a PR.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, prNumber, tokensUsed, model
+ */
+export async function resolveIssue(context) {
+  const { octokit, repo, config, issueNumber, instructions, writablePaths, testCommand, model } = context;
+
+  if (!issueNumber) {
+    throw new Error("resolve-issue task requires issue-number input");
+  }
+
+  // Safety: check if issue is already resolved
+  if (await isIssueResolved(octokit, repo, issueNumber)) {
+    core.info(`Issue #${issueNumber} is already closed. Returning nop.`);
+    return { outcome: "nop", details: "Issue already resolved" };
+  }
+
+  // Safety: check attempt limits
+  const branchPrefix = "agentic-lib-issue-";
+  const { allowed, attempts } = await checkAttemptLimit(
+    octokit,
+    repo,
+    issueNumber,
+    branchPrefix,
+    config.attemptsPerIssue,
+  );
+  if (!allowed) {
+    core.warning(`Issue #${issueNumber} has exceeded attempt limit (${attempts}/${config.attemptsPerIssue})`);
+    return { outcome: "attempt-limit-exceeded", details: `${attempts} attempts exhausted` };
+  }
+
+  // Safety: check WIP limits
+  const wipCheck = await checkWipLimit(octokit, repo, "in-progress", config.featureDevelopmentIssuesWipLimit);
+  if (!wipCheck.allowed) {
+    core.info(`WIP limit reached (${wipCheck.count}/${config.featureDevelopmentIssuesWipLimit}). Returning nop.`);
+    return { outcome: "wip-limit-reached", details: `${wipCheck.count} issues in progress` };
+  }
+
+  // Fetch the issue and comments
+  const [{ data: issue }, { data: comments }] = await Promise.all([
+    octokit.rest.issues.get({ ...repo, issue_number: Number(issueNumber) }),
+    octokit.rest.issues.listComments({ ...repo, issue_number: Number(issueNumber), per_page: 10 }),
+  ]);
+
+  const contributing = readOptionalFile(config.paths.contributing.path);
+  const agentInstructions = instructions || "Resolve the GitHub issue by writing code that satisfies the requirements.";
+  const readOnlyPaths = config.readOnlyPaths;
+
+  const prompt = [
+    "## Instructions",
+    agentInstructions,
+    "",
+    "## Issue",
+    `#${issueNumber}: ${issue.title}`,
+    "",
+    issue.body || "(no description)",
+    "",
+    comments.length > 0 ? "## Issue Comments" : "",
+    ...comments.map((c) => `**${c.user.login}:** ${c.body}`),
+    "",
+    formatPathsSection(writablePaths, readOnlyPaths),
+    "",
+    "## Constraints",
+    `- Run \`${testCommand}\` to validate your changes`,
+    contributing ? `\n## Contributing Guidelines\n${contributing}` : "",
+  ].join("\n");
+
+  const { content: resultContent, tokensUsed } = await runCopilotTask({
+    model,
+    systemMessage: `You are an autonomous coding agent resolving GitHub issue #${issueNumber}. Write clean, tested code. Only modify files listed under "Writable" paths. Read-only paths are for context only.`,
+    prompt,
+    writablePaths,
+  });
+
+  core.info(`Copilot SDK response received (${tokensUsed} tokens)`);
+
+  return {
+    outcome: "code-generated",
+    prNumber: null,
+    tokensUsed,
+    model,
+    commitUrl: null,
+    details: `Generated code for issue #${issueNumber}: ${resultContent.substring(0, 200)}`,
+  };
+}

package/src/actions/agentic-step/tasks/review-issue.js

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tasks/review-issue.js — Review issues and close resolved ones
+//
+// Checks open issues against the current codebase to determine
+// if they have been resolved, and closes them if so.
+
+import * as core from "@actions/core";
+import { runCopilotTask, scanDirectory } from "../copilot.js";
+
+/**
+ * Review open issues and close those that have been resolved.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ */
+export async function reviewIssue(context) {
+  const { octokit, repo, config, issueNumber, instructions, model } = context;
+
+  // If no specific issue, review the oldest open automated issue
+  let targetIssueNumber = issueNumber;
+  if (!targetIssueNumber) {
+    const { data: openIssues } = await octokit.rest.issues.listForRepo({
+      ...repo,
+      state: "open",
+      labels: "automated",
+      per_page: 1,
+      sort: "created",
+      direction: "asc",
+    });
+    if (openIssues.length === 0) {
+      return { outcome: "nop", details: "No open automated issues to review" };
+    }
+    targetIssueNumber = openIssues[0].number;
+  }
+
+  const { data: issue } = await octokit.rest.issues.get({
+    ...repo,
+    issue_number: Number(targetIssueNumber),
+  });
+
+  if (issue.state === "closed") {
+    return { outcome: "nop", details: `Issue #${targetIssueNumber} is already closed` };
+  }
+
+  const sourceFiles = scanDirectory(config.paths.source.path, [".js", ".ts"], {
+    contentLimit: 2000,
+    recursive: true,
+  });
+  const testFiles = scanDirectory(config.paths.tests.path, [".test.js", ".test.ts"], {
+    contentLimit: 2000,
+    recursive: true,
+  });
+
+  const agentInstructions = instructions || "Review whether this issue has been resolved by the current codebase.";
+
+  const prompt = [
+    "## Instructions",
+    agentInstructions,
+    "",
+    `## Issue #${targetIssueNumber}: ${issue.title}`,
+    issue.body || "(no description)",
+    "",
+    `## Current Source (${sourceFiles.length} files)`,
+    ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
+    "",
+    `## Current Tests (${testFiles.length} files)`,
+    ...testFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
+    "",
+    "## Your Task",
+    "Determine if this issue has been resolved by the current code.",
+    "Respond with exactly one of:",
+    '- "RESOLVED: <reason>" if the issue is satisfied by the current code',
+    '- "OPEN: <reason>" if the issue is not yet resolved',
+  ].join("\n");
+
+  const { content: verdict, tokensUsed } = await runCopilotTask({
+    model,
+    systemMessage: "You are a code reviewer determining if GitHub issues have been resolved.",
+    prompt,
+    writablePaths: [],
+  });
+
+  if (verdict.toUpperCase().startsWith("RESOLVED")) {
+    await octokit.rest.issues.createComment({
+      ...repo,
+      issue_number: Number(targetIssueNumber),
+      body: [
+        "**Automated Review Result:** This issue has been resolved by the current codebase.",
+        "",
+        `**Task:** review-issue`,
+        `**Model:** ${model}`,
+        `**Source files reviewed:** ${sourceFiles.length}`,
+        `**Test files reviewed:** ${testFiles.length}`,
+        "",
+        verdict,
+      ].join("\n"),
+    });
+    await octokit.rest.issues.update({
+      ...repo,
+      issue_number: Number(targetIssueNumber),
+      state: "closed",
+    });
+    core.info(`Issue #${targetIssueNumber} closed as resolved`);
+
+    return {
+      outcome: "issue-closed",
+      tokensUsed,
+      model,
+      details: `Closed issue #${targetIssueNumber}: ${verdict.substring(0, 200)}`,
+    };
+  }
+
+  core.info(`Issue #${targetIssueNumber} still open: ${verdict.substring(0, 100)}`);
+  return {
+    outcome: "issue-still-open",
+    tokensUsed,
+    model,
+    details: `Issue #${targetIssueNumber} remains open: ${verdict.substring(0, 200)}`,
+  };
+}

package/src/actions/agentic-step/tasks/transform.js

@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tasks/transform.js — Full mission → features → issues → code pipeline
+//
+// Reads the mission, analyzes the current state, identifies what to build next,
+// and either creates features, issues, or code.
+
+import * as core from "@actions/core";
+import { runCopilotTask, readOptionalFile, scanDirectory, formatPathsSection } from "../copilot.js";
+
+/**
+ * Run the full transformation pipeline from mission to code.
+ *
+ * @param {Object} context - Task context from index.js
+ * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ */
+export async function transform(context) {
+  const { config, instructions, writablePaths, testCommand, model, octokit, repo } = context;
+
+  // Read mission (required)
+  const mission = readOptionalFile(config.paths.mission.path);
+  if (!mission) {
+    core.warning(`No mission file found at ${config.paths.mission.path}`);
+    return { outcome: "nop", details: "No mission file found" };
+  }
+
+  const features = scanDirectory(config.paths.features.path, ".md");
+  const sourceFiles = scanDirectory(config.paths.source.path, [".js", ".ts"], {
+    contentLimit: 2000,
+    recursive: true,
+  });
+
+  const { data: openIssues } = await octokit.rest.issues.listForRepo({
+    ...repo,
+    state: "open",
+    per_page: 20,
+  });
+
+  const agentInstructions =
+    instructions || "Transform the repository toward its mission by identifying the next best action.";
+  const readOnlyPaths = config.readOnlyPaths;
+
+  // TDD mode: split into test-first + implementation phases
+  if (config.tdd === true) {
+    return await transformTdd({
+      config,
+      instructions: agentInstructions,
+      writablePaths,
+      readOnlyPaths,
+      testCommand,
+      model,
+      mission,
+      features,
+      sourceFiles,
+      openIssues,
+    });
+  }
+
+  const prompt = [
+    "## Instructions",
+    agentInstructions,
+    "",
+    "## Mission",
+    mission,
+    "",
+    `## Current Features (${features.length})`,
+    ...features.map((f) => `### ${f.name}\n${f.content.substring(0, 500)}`),
+    "",
+    `## Current Source Files (${sourceFiles.length})`,
+    ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
+    "",
+    `## Open Issues (${openIssues.length})`,
+    ...openIssues.slice(0, 10).map((i) => `- #${i.number}: ${i.title}`),
+    "",
+    "## Your Task",
+    "Analyze the mission, features, source code, and open issues.",
+    "Determine the single most impactful next step to transform this repository.",
+    "Then implement that step.",
+    "",
+    formatPathsSection(writablePaths, readOnlyPaths),
+    "",
+    "## Constraints",
+    `- Run \`${testCommand}\` to validate your changes`,
+  ].join("\n");
+
+  core.info(`Transform prompt length: ${prompt.length} chars`);
+
+  const { content: resultContent, tokensUsed } = await runCopilotTask({
+    model,
+    systemMessage:
+      "You are an autonomous code transformation agent. Your goal is to advance the repository toward its mission by making the most impactful change possible in a single step.",
+    prompt,
+    writablePaths,
+  });
+
+  core.info(`Transformation step completed (${tokensUsed} tokens)`);
+
+  return {
+    outcome: "transformed",
+    tokensUsed,
+    model,
+    details: resultContent.substring(0, 500),
+  };
+}
+
+/**
+ * TDD-mode transformation: Phase 1 creates a failing test, Phase 2 writes implementation.
+ */
+async function transformTdd({
+  config: _config,
+  instructions,
+  writablePaths,
+  readOnlyPaths,
+  testCommand,
+  model,
+  mission,
+  features,
+  sourceFiles,
+  openIssues,
+}) {
+  let totalTokens = 0;
+
+  // Phase 1: Create a failing test
+  core.info("TDD Phase 1: Creating failing test");
+
+  const testPrompt = [
+    "## Instructions",
+    instructions,
+    "",
+    "## Mode: TDD Phase 1 — Write Failing Test",
+    "You are in TDD mode. In this phase, you must ONLY write a test.",
+    "The test should capture the next feature requirement based on the mission and current state.",
+    "The test MUST fail against the current codebase (it tests something not yet implemented).",
+    "Do NOT write any implementation code in this phase.",
+    "",
+    "## Mission",
+    mission,
+    "",
+    `## Current Features (${features.length})`,
+    ...features.map((f) => `### ${f.name}\n${f.content.substring(0, 500)}`),
+    "",
+    `## Current Source Files (${sourceFiles.length})`,
+    ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
+    "",
+    `## Open Issues (${openIssues.length})`,
+    ...openIssues.slice(0, 10).map((i) => `- #${i.number}: ${i.title}`),
+    "",
+    formatPathsSection(writablePaths, readOnlyPaths),
+    "",
+    "## Constraints",
+    "- Write ONLY test code in this phase",
+    "- The test must fail when run (it tests unimplemented functionality)",
+    `- Run \`${testCommand}\` to confirm the test fails`,
+  ].join("\n");
+
+  const phase1 = await runCopilotTask({
+    model,
+    systemMessage:
+      "You are a TDD agent. In this phase, write ONLY a failing test that captures the next feature requirement. Do not write implementation code.",
+    prompt: testPrompt,
+    writablePaths,
+  });
+  totalTokens += phase1.tokensUsed;
+  const testResult = phase1.content;
+
+  core.info(`TDD Phase 1 completed (${totalTokens} tokens): test created`);
+
+  // Phase 2: Write implementation to make the test pass
+  core.info("TDD Phase 2: Writing implementation");
+
+  const implPrompt = [
+    "## Instructions",
+    instructions,
+    "",
+    "## Mode: TDD Phase 2 — Write Implementation",
+    "A failing test has been written in Phase 1. Your job is to write the MINIMUM implementation",
+    "code needed to make the test pass. Do not modify the test.",
+    "",
+    "## What was done in Phase 1",
+    testResult.substring(0, 1000),
+    "",
+    "## Mission",
+    mission,
+    "",
+    `## Current Source Files (${sourceFiles.length})`,
+    ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
+    "",
+    formatPathsSection(writablePaths, readOnlyPaths),
+    "",
+    "## Constraints",
+    "- Write implementation code to make the failing test pass",
+    "- Do NOT modify the test file created in Phase 1",
+    `- Run \`${testCommand}\` to confirm all tests pass`,
+  ].join("\n");
+
+  const phase2 = await runCopilotTask({
+    model,
+    systemMessage:
+      "You are a TDD agent. A failing test was written in Phase 1. Write the minimum implementation to make it pass. Do not modify the test.",
+    prompt: implPrompt,
+    writablePaths,
+  });
+  totalTokens += phase2.tokensUsed;
+
+  core.info(`TDD Phase 2 completed (total ${totalTokens} tokens)`);
+
+  return {
+    outcome: "transformed-tdd",
+    tokensUsed: totalTokens,
+    model,
+    details: `TDD transformation: Phase 1 (failing test) + Phase 2 (implementation). ${testResult.substring(0, 200)}`,
+  };
+}

package/src/actions/agentic-step/tools.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// tools.js — Shared tool definitions for agentic-step task handlers
+//
+// Defines file I/O and shell tools using the Copilot SDK's defineTool().
+// The agent has no built-in filesystem access — these tools give it the
+// ability to read, write, list files, and run commands.
+
+import { defineTool } from "@github/copilot-sdk";
+import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync } from "fs";
+import { execSync } from "child_process";
+import { dirname, resolve } from "path";
+import { isPathWritable } from "./safety.js";
+import * as core from "@actions/core";
+
+/**
+ * Create the standard set of agent tools.
+ *
+ * @param {string[]} writablePaths - Paths the agent is allowed to write to
+ * @returns {import('@github/copilot-sdk').Tool[]} Array of tools for createSession()
+ */
+export function createAgentTools(writablePaths) {
+  const readFile = defineTool("read_file", {
+    description: "Read the contents of a file at the given path.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute or relative file path to read" },
+      },
+      required: ["path"],
+    },
+    handler: ({ path }) => {
+      const resolved = resolve(path);
+      core.info(`[tool] read_file: ${resolved}`);
+      if (!existsSync(resolved)) {
+        return { error: `File not found: ${resolved}` };
+      }
+      try {
+        const content = readFileSync(resolved, "utf8");
+        return { content };
+      } catch (err) {
+        return { error: `Failed to read ${resolved}: ${err.message}` };
+      }
+    },
+  });
+
+  const writeFile = defineTool("write_file", {
+    description:
+      "Write content to a file. The file will be created if it does not exist. Parent directories will be created automatically. Only writable paths are allowed.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute or relative file path to write" },
+        content: { type: "string", description: "The full content to write to the file" },
+      },
+      required: ["path", "content"],
+    },
+    handler: ({ path, content }) => {
+      const resolved = resolve(path);
+      core.info(`[tool] write_file: ${resolved}`);
+      if (!isPathWritable(resolved, writablePaths) && !isPathWritable(path, writablePaths)) {
+        return { error: `Path is not writable: ${path}. Writable paths: ${writablePaths.join(", ")}` };
+      }
+      try {
+        const dir = dirname(resolved);
+        if (!existsSync(dir)) {
+          mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(resolved, content, "utf8");
+        return { success: true, path: resolved };
+      } catch (err) {
+        return { error: `Failed to write ${resolved}: ${err.message}` };
+      }
+    },
+  });
+
+  const listFiles = defineTool("list_files", {
+    description: "List files and directories at the given path. Returns names with a trailing / for directories.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory path to list" },
+        recursive: { type: "boolean", description: "Whether to list recursively (default false)" },
+      },
+      required: ["path"],
+    },
+    handler: ({ path, recursive }) => {
+      const resolved = resolve(path);
+      core.info(`[tool] list_files: ${resolved} (recursive=${!!recursive})`);
+      if (!existsSync(resolved)) {
+        return { error: `Directory not found: ${resolved}` };
+      }
+      try {
+        const entries = readdirSync(resolved, { withFileTypes: true, recursive: !!recursive });
+        const names = entries.map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+        return { files: names };
+      } catch (err) {
+        return { error: `Failed to list ${resolved}: ${err.message}` };
+      }
+    },
+  });
+
+  const runCommand = defineTool("run_command", {
+    description:
+      "Run a shell command and return its stdout and stderr. Use this to run tests, build, lint, or inspect the environment.",
+    parameters: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: "The shell command to execute" },
+        cwd: { type: "string", description: "Working directory for the command (default: current directory)" },
+      },
+      required: ["command"],
+    },
+    handler: ({ command, cwd }) => {
+      const workDir = cwd ? resolve(cwd) : process.cwd();
+      core.info(`[tool] run_command: ${command} (cwd=${workDir})`);
+      const blocked = /\bgit\s+(commit|push|add|reset|checkout|rebase|merge|stash)\b/;
+      if (blocked.test(command)) {
+        core.info(`[tool] BLOCKED git write command: ${command}`);
+        return { error: "Git write commands are not allowed. Use read_file/write_file tools instead." };
+      }
+      try {
+        const stdout = execSync(command, {
+          cwd: workDir,
+          encoding: "utf8",
+          timeout: 120000,
+          maxBuffer: 1024 * 1024,
+        });
+        return { stdout, exitCode: 0 };
+      } catch (err) {
+        return {
+          stdout: err.stdout || "",
+          stderr: err.stderr || "",
+          exitCode: err.status || 1,
+          error: err.message,
+        };
+      }
+    },
+  });
+
+  return [readFile, writeFile, listFiles, runCommand];
+}

package/src/actions/commit-if-changed/action.yml

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2025-2026 Polycode Limited
+# .github/agentic-lib/actions/commit-if-changed/action.yml
+#
+# Composite action: Commit and push if there are staged changes.
+# Replaces the 8-line block repeated across 6 agent workflows.
+
+name: "Commit if changed"
+description: "Stage all changes, commit if any exist, and push"
+
+inputs:
+  commit-message:
+    description: "Commit message"
+    required: true
+  push-ref:
+    description: "Branch ref to push to (default: current ref_name)"
+    required: false
+    default: ""
+
+runs:
+  using: "composite"
+  steps:
+    - name: Commit and push if changed
+      shell: bash
+      run: |
+        git config --local user.email 'action@github.com'
+        git config --local user.name 'GitHub Actions[bot]'
+        git add -A
+        if git diff --cached --quiet; then
+          echo "No changes to commit"
+        else
+          git commit -m "${{ inputs.commit-message }}"
+          REF="${{ inputs.push-ref }}"
+          if [ -n "$REF" ]; then
+            git push origin "$REF"
+          else
+            git push
+          fi
+        fi

package/src/actions/setup-npmrc/action.yml

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2025-2026 Polycode Limited
+# .github/agentic-lib/actions/setup-npmrc/action.yml
+#
+# Composite action: Set up .npmrc for GitHub Packages authentication.
+# Replaces the 7-line block repeated across 11+ workflows.
+
+name: "Setup .npmrc"
+description: "Configure .npmrc for GitHub Packages authentication"
+
+inputs:
+  npm-auth-organisation:
+    description: "npm scope (e.g. @xn-intenton-z2a). If empty, skip setup."
+    required: false
+    default: ""
+  token:
+    description: "GitHub token for npm authentication"
+    required: true
+  target:
+    description: 'Where to write .npmrc: "home" (~/.npmrc) or "project" (.npmrc)'
+    required: false
+    default: "project"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up .npmrc
+      if: ${{ inputs.npm-auth-organisation != '' }}
+      shell: bash
+      run: |
+        if [ "${{ inputs.target }}" = "home" ]; then
+          NPMRC="$HOME/.npmrc"
+        else
+          NPMRC=".npmrc"
+        fi
+        echo "${{ inputs.npm-auth-organisation }}:registry=https://npm.pkg.github.com" >> "$NPMRC"
+        echo "//npm.pkg.github.com/:_authToken=${{ inputs.token }}" >> "$NPMRC"
+        echo "always-auth=true" >> "$NPMRC"

package/src/agents/agent-apply-fix.md

@@ -0,0 +1,13 @@
+You are providing the entire new content of source files, test files, documentation files,
+and other necessary files with all necessary changes applied to resolve a possible build or test
+problem. Focus on high-impact, functional fixes that address core issues rather than superficial
+changes or excessive debugging or validation. If the problem is in an area of the code with little
+value you may re-implement it or remove it.
+
+Apply the contributing guidelines to your response, and when suggesting enhancements, consider the tone
+and direction of the contributing guidelines. Prioritize changes that deliver substantial user value
+and maintain the integrity of the codebase's primary purpose.
+
+You may complete the implementation of a feature and/or bring the code output in line with the README
+or other documentation. Do as much as you can all at once so that the build runs (even with nothing
+to build) and the tests pass and the main at least doesn't output an error.