@nt-ai-lab/opencode-skillz 0.3.15 → 0.4.2

package/dist/git-workflow-gates.js

@@ -0,0 +1,103 @@
+export const directPullRequestCreationBlockedMessage = [
+    "Direct gh pr create is banned for this workspace.",
+    "Use nt_skillz_create_pr instead.",
+].join("\n");
+class GitWorkflowGateError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+function readBashCommandText(value) {
+    if (typeof value !== "string") {
+        throw new GitWorkflowGateError(`Expected bash command text. Got ${String(value)}.`);
+    }
+    return value.trim();
+}
+function readCommandFailureMessage(commandResult) {
+    const stderr = commandResult.stderr.trim();
+    if (stderr) {
+        return stderr;
+    }
+    const stdout = commandResult.stdout.trim();
+    if (stdout) {
+        return stdout;
+    }
+    return `exit status ${commandResult.status}`;
+}
+function isDirectPullRequestCreation(commandText) {
+    return /(?:^|[;&|()]|\s)gh\s+pr\s+create(?:\s|$|[;&|()])/.test(commandText);
+}
+function isGitCommit(commandText) {
+    return /(?:^|[;&|()]|\s)git\s+commit(?:\s|$|[;&|()])/.test(commandText);
+}
+function normalizeCommandOutput(commandResult, description) {
+    if (commandResult.errorMessage) {
+        throw new GitWorkflowGateError(`Expected ${description} to run. Got ${commandResult.errorMessage}.`);
+    }
+    if (commandResult.status !== 0) {
+        throw new GitWorkflowGateError(`Expected ${description} to succeed. Got ${readCommandFailureMessage(commandResult)}.`);
+    }
+    return commandResult.stdout.trim();
+}
+function isTypeScriptFilePath(filePath) {
+    return filePath.endsWith(".ts") || filePath.endsWith(".tsx");
+}
+function createUnlintedCommitMessage(filePaths) {
+    return [
+        "Commit blocked: TypeScript files changed without nt_skillz_lint validation.",
+        `Run nt_skillz_lint with files: ${JSON.stringify(filePaths)}`,
+        "Then retry the commit.",
+    ].join("\n");
+}
+export function createGitWorkflowGate(repositoryRoot, commandRunner) {
+    const lintedFingerprints = new Map();
+    function runGit(commandArguments, description) {
+        return normalizeCommandOutput(commandRunner.run("git", commandArguments, repositoryRoot), description);
+    }
+    function readWorkingTreeFingerprint(filePath) {
+        return runGit(["hash-object", "--", filePath], `working tree hash for ${filePath}`);
+    }
+    function readStagedFingerprint(filePath) {
+        return runGit(["rev-parse", `:${filePath}`], `staged hash for ${filePath}`);
+    }
+    function readStagedTypeScriptFilePaths() {
+        const output = runGit([
+            "diff",
+            "--name-only",
+            "--cached",
+            "--diff-filter=ACMR",
+            "--",
+            "*.ts",
+            "*.tsx",
+        ], "staged TypeScript file discovery");
+        return output.split("\n").map((filePath) => filePath.trim()).filter(Boolean);
+    }
+    function ensureStagedTypeScriptFilesAreLinted() {
+        const stagedFilePaths = readStagedTypeScriptFilePaths();
+        const unlintedFilePaths = stagedFilePaths.filter((filePath) => lintedFingerprints.get(filePath) !== readStagedFingerprint(filePath));
+        if (unlintedFilePaths.length === 0) {
+            return;
+        }
+        throw new GitWorkflowGateError(createUnlintedCommitMessage(unlintedFilePaths));
+    }
+    return {
+        beforeToolExecution(input, output) {
+            if (input.tool !== "bash") {
+                return;
+            }
+            const commandText = readBashCommandText(output.args.command);
+            if (isDirectPullRequestCreation(commandText)) {
+                throw new GitWorkflowGateError(directPullRequestCreationBlockedMessage);
+            }
+            if (isGitCommit(commandText)) {
+                ensureStagedTypeScriptFilesAreLinted();
+            }
+        },
+        recordLintedFiles(filePaths) {
+            const typeScriptFilePaths = filePaths.filter(isTypeScriptFilePath);
+            for (const filePath of typeScriptFilePaths) {
+                lintedFingerprints.set(filePath, readWorkingTreeFingerprint(filePath));
+            }
+        },
+    };
+}

package/dist/plugin-registry/agents.js

@@ -15,8 +15,6 @@ function getParentAgentName(rawAgent) {
 }
 function appendAgentPromptParts(promptParts, rawAgents, name) {
     const rawAgent = rawAgents[name];
-    if (!rawAgent)
-        return;
     const parentAgentName = getParentAgentName(rawAgent);
     if (parentAgentName && rawAgents[parentAgentName]?.body) {
         promptParts.push(rawAgents[parentAgentName].body);
@@ -47,8 +45,6 @@ export function registerAgents(agentConfig, pluginRoot, commands) {
     const rawAgents = readMarkdownEntries(pluginRoot, "agents");
     function collectPreloadedCommands(agentName, stack = new Set()) {
         const rawAgent = rawAgents[agentName];
-        if (!rawAgent)
-            return [];
         if (stack.has(agentName))
             return parseCsvList(rawAgent.meta.preload_commands);
         stack.add(agentName);

package/dist/plugin-registry/commands.js

@@ -19,8 +19,6 @@ function loadMarkdownCommands(pluginRoot) {
     const commands = {};
     function buildComposedTemplate(name, stack = new Set()) {
         const rawCommand = rawCommands[name];
-        if (!rawCommand)
-            return "";
         if (stack.has(name))
             return rawCommand.body;
         stack.add(name);

package/dist/plugin-registry/index.js

@@ -1,16 +1,43 @@
+import process from "node:process";
 import { createDontStopHooks } from "../commands/dont-stop/index.js";
+import { createGitWorkflowGate, } from "../git-workflow-gates.js";
+import { createPullRequestTool, } from "../tools/create-pr-tool.js";
 import { LINT_TOOL_NAME, lintTool, } from "../tools/lint.js";
-import { VITEST_COVERAGE_TOOL_NAME, vitestCoverageTool, } from "../tools/vitest-coverage.js";
+import { PULL_REQUEST_FEEDBACK_TOOL_NAME, pullRequestFeedbackTool, } from "../tools/pull-request-feedback-tool.js";
+import { VITEST_COVERAGE_TOOL_NAME, vitestCoverageTool, } from "../tools/vitest-coverage-tool.js";
 import { registerAgents } from "./agents.js";
 import { registerCommands } from "./commands.js";
+import { childProcessCommandRunner } from "../tools/infra/source-control/changed-files.js";
+function readLintedFilePaths(request) {
+    if (!Array.isArray(request.files)) {
+        return [];
+    }
+    return request.files.filter((filePath) => typeof filePath === "string");
+}
+function createGateAwareLintTool(gate) {
+    return {
+        ...lintTool,
+        async execute(request, context) {
+            const result = await lintTool.execute(request, context);
+            gate.recordLintedFiles(readLintedFilePaths(request));
+            return result;
+        },
+    };
+}
 export function createPluginRegistry(input, pluginRoot) {
     const dontStopHooks = createDontStopHooks(input.client);
+    const gitWorkflowGate = createGitWorkflowGate(input.worktree ?? process.cwd(), childProcessCommandRunner);
     return {
         ...dontStopHooks,
         tool: {
-            [LINT_TOOL_NAME]: lintTool,
+            nt_skillz_create_pr: createPullRequestTool,
+            [LINT_TOOL_NAME]: createGateAwareLintTool(gitWorkflowGate),
+            [PULL_REQUEST_FEEDBACK_TOOL_NAME]: pullRequestFeedbackTool,
             [VITEST_COVERAGE_TOOL_NAME]: vitestCoverageTool,
         },
+        "tool.execute.before": async (hookInput, hookOutput) => {
+            gitWorkflowGate.beforeToolExecution(hookInput, hookOutput);
+        },
         config: async (config) => {
             config.command ??= {};
             config.agent ??= {};

package/dist/tools/create-pr-tool.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { CommandRunner } from "../git-workflow-gates.js";
+export declare function createPullRequestToolWithRunner(commandRunner: CommandRunner): ToolDefinition;
+export declare const createPullRequestTool: ToolDefinition;

package/dist/tools/create-pr-tool.js

@@ -0,0 +1,22 @@
+import { tool } from "@opencode-ai/plugin";
+import { createDraftPullRequest } from "./infra/pull-request/create-draft-pull-request.js";
+import { childProcessCommandRunner } from "./infra/source-control/changed-files.js";
+export function createPullRequestToolWithRunner(commandRunner) {
+    return tool({
+        description: "Create a validated draft pull request with required OpenCode workflow gates.",
+        args: {
+            base: tool.schema.string().describe("Base branch for the pull request."),
+            title: tool.schema.string().describe("Pull request title."),
+            problem: tool.schema.string().describe("Problem section content."),
+            solution: tool.schema.string().describe("Solution section content."),
+            acceptanceCriteria: tool.schema.string().describe("Acceptance Criteria section content."),
+            architectureAndSoftwareDesign: tool.schema.string().describe("Architecture and software design section content."),
+        },
+        async execute(request, context) {
+            return {
+                output: createDraftPullRequest(context.worktree, request, commandRunner),
+            };
+        },
+    });
+}
+export const createPullRequestTool = createPullRequestToolWithRunner(childProcessCommandRunner);

package/dist/tools/infra/lint/guidance.d.ts

@@ -0,0 +1,8 @@
+interface LintMessageWithRule {
+    ruleId: string | null;
+}
+interface LintResultWithMessages {
+    messages: readonly LintMessageWithRule[];
+}
+export declare function createLintFailureGuidance(lintResults: readonly LintResultWithMessages[]): string;
+export {};

package/dist/tools/infra/lint/guidance.js

@@ -0,0 +1,98 @@
+const genericLintFailureGuidance = [
+    "Lint remediation guidance:",
+    "- Do not sacrifice code quality or test coverage to satisfy lint rules.",
+    "- These rules are not objectives; they are signs that code needs to be split, simplified, or clarified.",
+    "- Fix the underlying design or test issue instead of deleting assertions, disabling rules, or reducing coverage.",
+];
+const targetedLintGuidance = [
+    {
+        ruleIds: ["vitest/max-expects"],
+        guidance: [
+            "Do not delete required assertions or weaken expected values to reduce assertion count.",
+            "If several assertions describe one observable result, prefer one whole-result assertion such as `toEqual`, `toStrictEqual`, `toMatchObject`, or a domain-specific matcher.",
+            "If the test verifies multiple behaviours, split it into separate tests with outcome-focused names.",
+            "Do not combine unrelated checks into one object assertion just to satisfy this rule.",
+        ],
+    },
+    {
+        ruleIds: ["max-lines", "sonarjs/max-lines", "sonarjs/max-lines-per-function"],
+        guidance: [
+            "Do not delete required behavior, tests, setup, edge cases, or assertions to reduce line count.",
+            "Split by cohesive responsibility instead: production behavior, test fixture construction, assertions, adapters, or domain concepts.",
+            "For long spec files, extract fixture builders or split scenarios by behavior.",
+            "For long source files, extract named concepts that can be tested independently.",
+            "Do not move unrelated code into vague files such as utils, helpers, common, shared, or lib.",
+        ],
+    },
+    {
+        ruleIds: [
+            "complexity",
+            "max-depth",
+            "sonarjs/cognitive-complexity",
+            "sonarjs/cyclomatic-complexity",
+            "sonarjs/nested-control-flow",
+        ],
+        guidance: [
+            "Do not remove branches, states, error handling, or edge cases to reduce complexity.",
+            "Reduce complexity by making decisions easier to read without changing behavior.",
+            "Use guard clauses, early returns, named predicates, or discriminated unions where they clarify the code.",
+            "If complexity comes from multiple states, model those states directly instead of stacking conditionals.",
+            "Keep all existing behavior, tests, and edge cases intact.",
+        ],
+    },
+    {
+        ruleIds: [
+            "@typescript-eslint/no-explicit-any",
+            "@typescript-eslint/no-unsafe-assignment",
+            "@typescript-eslint/no-unsafe-call",
+            "@typescript-eslint/no-unsafe-member-access",
+            "@typescript-eslint/no-unsafe-return",
+            "@typescript-eslint/consistent-type-assertions",
+            "@typescript-eslint/no-non-null-assertion",
+            "sonarjs/no-return-type-any",
+        ],
+        guidance: [
+            "Do not replace `any` with `unknown as X`, non-null assertions, type assertions, or broader unsafe types.",
+            "Add precise types at the boundary where the value enters the system.",
+            "For external input, parse with Zod or an existing runtime validator.",
+            "For impossible states, change the type model instead of silencing the error.",
+            "Keep behavior unchanged and preserve existing validation.",
+        ],
+    },
+    {
+        ruleIds: [
+            "@eslint-community/eslint-comments/no-use",
+            "no-inline-comments",
+            "sonarjs/no-commented-code",
+            "sonarjs/no-sonar-comments",
+            "@typescript-eslint/ban-ts-comment",
+        ],
+        guidance: [
+            "Do not add code comments. They make the code noisy and are a workaround for poor code. Make code intention revealing so that comments are not necessary.",
+            "Do not add lint or TypeScript suppressions. The rules are non-negotiable. If the solution cannot be implemented while following the codebase rules, stop and ask for help.",
+        ],
+    },
+];
+function isPresentRuleId(ruleId) {
+    return typeof ruleId === "string" && ruleId.length > 0;
+}
+function readTriggeredRuleIds(lintResults) {
+    return new Set(lintResults.flatMap((lintResult) => {
+        return lintResult.messages.map((message) => message.ruleId).filter(isPresentRuleId);
+    }));
+}
+export function createLintFailureGuidance(lintResults) {
+    const triggeredRuleIds = readTriggeredRuleIds(lintResults);
+    const specificGuidance = targetedLintGuidance
+        .filter((targetedGuidance) => targetedGuidance.ruleIds.some((ruleId) => triggeredRuleIds.has(ruleId)))
+        .flatMap((targetedGuidance) => targetedGuidance.guidance);
+    if (specificGuidance.length === 0) {
+        return genericLintFailureGuidance.join("\n");
+    }
+    return [
+        ...genericLintFailureGuidance,
+        "",
+        "Rule-specific guidance:",
+        ...specificGuidance.map((guidance) => `- ${guidance}`),
+    ].join("\n");
+}

package/dist/tools/{lint-review.d.ts → infra/lint/review.d.ts}

@@ -1,4 +1,4 @@
-import { type CommandRunner } from "./pull-request-files.js";
+import { type CommandRunner } from "../source-control/changed-files.js";
 export interface LintReviewRequest {
     repositoryRoot?: string;
     pullRequest?: string;

package/dist/tools/{lint-review.js → infra/lint/review.js}

@@ -1,6 +1,6 @@
 import path from "node:path";
 import process from "node:process";
-import { resolvePullRequestChangedFiles, } from "./pull-request-files.js";
+import { resolvePullRequestChangedFiles, } from "../source-control/changed-files.js";
 function normalizeTypeScriptFiles(filePaths) {
     return filePaths.filter((filePath) => filePath.endsWith(".ts") || filePath.endsWith(".tsx"));
 }

package/dist/tools/infra/pull-request/create-draft-pull-request.d.ts

@@ -0,0 +1,11 @@
+import type { CommandRunner } from "../../../git-workflow-gates.js";
+export declare const CREATE_PULL_REQUEST_TOOL_NAME = "nt_skillz_create_pr";
+export interface CreatePullRequestRequest {
+    base: string;
+    title: string;
+    problem: string;
+    solution: string;
+    acceptanceCriteria: string;
+    architectureAndSoftwareDesign: string;
+}
+export declare function createDraftPullRequest(repositoryRoot: string, request: CreatePullRequestRequest, commandRunner: CommandRunner): string;

package/dist/tools/infra/pull-request/create-draft-pull-request.js

@@ -0,0 +1,115 @@
+export const CREATE_PULL_REQUEST_TOOL_NAME = "nt_skillz_create_pr";
+const semanticCommitTitlePattern = /^(feat|fix|refactor|perf|docs|test|build|ci|release|chore)\([^)]+\): .+/;
+class CreatePullRequestError extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+function normalizeRequiredText(value, fieldName) {
+    const trimmedValue = value.trim();
+    if (trimmedValue) {
+        return trimmedValue;
+    }
+    throw new CreatePullRequestError(`Expected ${fieldName} to be provided. Got empty text.`);
+}
+function runCommand(repositoryRoot, commandRunner, executable, commandArguments, description) {
+    const commandResult = commandRunner.run(executable, commandArguments, repositoryRoot);
+    if (commandResult.errorMessage) {
+        throw new CreatePullRequestError(`Expected ${description} to run. Got ${commandResult.errorMessage}.`);
+    }
+    if (commandResult.status !== 0) {
+        throw new CreatePullRequestError(`Expected ${description} to succeed. Got ${readCommandFailureMessage(commandResult)}.`);
+    }
+    return commandResult.stdout.trim();
+}
+function readCommandFailureMessage(commandResult) {
+    const stderr = commandResult.stderr.trim();
+    if (stderr) {
+        return stderr;
+    }
+    const stdout = commandResult.stdout.trim();
+    if (stdout) {
+        return stdout;
+    }
+    return `exit status ${commandResult.status}`;
+}
+function validateCleanWorkingTree(repositoryRoot, commandRunner) {
+    const statusOutput = runCommand(repositoryRoot, commandRunner, "git", ["status", "--porcelain"], "working tree status check");
+    if (!statusOutput) {
+        return;
+    }
+    throw new CreatePullRequestError(`Expected working tree to be clean before pull request creation. Got ${statusOutput}.`);
+}
+function validateSemanticCommitTitles(repositoryRoot, commandRunner, base) {
+    const commitTitleOutput = runCommand(repositoryRoot, commandRunner, "git", ["log", "--format=%s", `${base}..HEAD`], "pull request commit title discovery");
+    const commitTitles = commitTitleOutput.split("\n").map((commitTitle) => commitTitle.trim()).filter(Boolean);
+    const invalidCommitTitle = commitTitles.find((commitTitle) => !semanticCommitTitlePattern.test(commitTitle));
+    if (!invalidCommitTitle) {
+        return;
+    }
+    throw new CreatePullRequestError(`Expected semantic commit title format <type>(<scope>): <short summary>. Got ${invalidCommitTitle}.`);
+}
+function readCurrentBranch(repositoryRoot, commandRunner) {
+    const branchName = runCommand(repositoryRoot, commandRunner, "git", ["branch", "--show-current"], "current branch discovery");
+    if (branchName) {
+        return branchName;
+    }
+    throw new CreatePullRequestError("Expected current branch name to be non-empty. Got empty text.");
+}
+function isMissingUpstreamResult(commandResult) {
+    if (commandResult.errorMessage) {
+        return false;
+    }
+    return readCommandFailureMessage(commandResult).includes("no upstream");
+}
+function readUpstreamLookupFailureMessage(commandResult) {
+    if (commandResult.errorMessage) {
+        return commandResult.errorMessage;
+    }
+    return readCommandFailureMessage(commandResult);
+}
+function pushBranchWhenUpstreamIsMissing(repositoryRoot, commandRunner, branchName) {
+    const upstreamResult = commandRunner.run("git", ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], repositoryRoot);
+    if (upstreamResult.status === 0) {
+        return;
+    }
+    if (!isMissingUpstreamResult(upstreamResult)) {
+        throw new CreatePullRequestError(`Expected upstream lookup to succeed or report missing upstream. Got ${readUpstreamLookupFailureMessage(upstreamResult)}.`);
+    }
+    runCommand(repositoryRoot, commandRunner, "git", ["push", "-u", "origin", branchName], "branch push");
+}
+function createPullRequestBody(request) {
+    return [
+        "## Problem",
+        normalizeRequiredText(request.problem, "problem"),
+        "",
+        "## Solution",
+        normalizeRequiredText(request.solution, "solution"),
+        "",
+        "## Acceptance Criteria",
+        normalizeRequiredText(request.acceptanceCriteria, "acceptanceCriteria"),
+        "",
+        "## Architecture and software design",
+        normalizeRequiredText(request.architectureAndSoftwareDesign, "architectureAndSoftwareDesign"),
+    ].join("\n");
+}
+export function createDraftPullRequest(repositoryRoot, request, commandRunner) {
+    const base = normalizeRequiredText(request.base, "base");
+    const title = normalizeRequiredText(request.title, "title");
+    const body = createPullRequestBody(request);
+    validateCleanWorkingTree(repositoryRoot, commandRunner);
+    validateSemanticCommitTitles(repositoryRoot, commandRunner, base);
+    const branchName = readCurrentBranch(repositoryRoot, commandRunner);
+    pushBranchWhenUpstreamIsMissing(repositoryRoot, commandRunner, branchName);
+    return runCommand(repositoryRoot, commandRunner, "gh", [
+        "pr",
+        "create",
+        "--draft",
+        "--base",
+        base,
+        "--title",
+        title,
+        "--body",
+        body,
+    ], "draft pull request creation");
+}

package/dist/tools/infra/pull-request/feedback.d.ts

@@ -0,0 +1,14 @@
+import type { CommandRunner } from "../source-control/changed-files.js";
+export declare const PULL_REQUEST_FEEDBACK_TOOL_NAME = "nt_skillz_pr_feedback";
+export declare class PullRequestFeedbackError extends Error {
+    constructor(message: string);
+}
+export interface PullRequestFeedbackRequest {
+    repositoryRoot: string;
+    pullRequestNumber: string;
+    pullRequestUrl: string;
+}
+export interface PullRequestFeedbackDependencies {
+    commandRunner?: CommandRunner;
+}
+export declare function readPullRequestFeedback(request: PullRequestFeedbackRequest, dependencies?: PullRequestFeedbackDependencies): string;