@webpieces/ai-hook-rules 0.3.291 → 0.3.293

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/ai-hook-rules",
-  "version": "0.3.291",
+  "version": "0.3.293",
   "description": "Pluggable write-time validation framework for AI coding agents (@webpieces/ai-hook-rules). Claude Code PreToolUse + openclaw before_tool_call adapters share one rule engine.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -35,7 +35,7 @@
     "directory": "packages/tooling/ai-hook-rules"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.3.291"
+    "@webpieces/rules-config": "0.3.293"
   },
   "publishConfig": {
     "access": "public"

package/src/core/rules/branch-creation-guard.js

@@ -15,9 +15,10 @@ const BRANCH_PATTERNS = [
     /git\s+switch\s+-[cC]\s+([^\s]+)/,
     /git\s+branch\s+(?!-[dDmMrRla])([^\s-][^\s]*)/,
 ];
-// The squash-merge tooling reserves a trailing `wp<number>` as its generation marker
-// (base → basewp2 → basewp3). A human branch ending that way would collide with it, so
-// block it at creation time and steer the name back to the plain feature form.
+// A trailing `wp<number>` was the old squash-merge generation marker (base → basewp2 → basewp3).
+// The tooling NO LONGER produces it — a sync now lands back on the same feature name — but the suffix
+// stays RESERVED so a human branch can't collide with a leftover `…wpN` still floating in a consumer
+// repo mid-transition. Block it at creation time and steer the name back to the plain feature form.
 const RESERVED_GENERATION_SUFFIX = /wp\d+$/;
 function extractBranchName(command) {
     for (const pattern of BRANCH_PATTERNS) {

package/src/core/rules/branch-creation-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"branch-creation-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/branch-creation-guard.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\n\nimport { BranchCreationGuardConfig } from '@webpieces/rules-config';\n\nimport type { BashContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { BashRuleBase } from '../rule-base';\nimport { FixHint, Option } from '../fix-hint';\n\n// Defaults used when the rule has no explicit value in webpieces.config.json.\n// branchFormat is a human sentence telling the AI how to name a branch created off main; it is\n// intentionally NOT the sub-branch convention (sub-branches are a separate, human-approved path).\nconst DEFAULT_BRANCH_FORMAT =\n    'Name it {whoami}/<short-feature-description> — lowercase, no version numbers, no sub/ prefix (e.g. dean/upgrade-webpieces)';\nconst DEFAULT_SUB_BRANCH_NAMING = 'feature/<ticket>/<short-description>';\n\nconst BRANCH_PATTERNS: RegExp[] = [\n    /git\\s+checkout\\s+-[bB]\\s+([^\\s]+)/,\n    /git\\s+switch\\s+-[cC]\\s+([^\\s]+)/,\n    /git\\s+branch\\s+(?!-[dDmMrRla])([^\\s-][^\\s]*)/,\n];\n\n// The squash-merge tooling reserves a trailing `wp<number>` as its generation marker\n// (base → basewp2 → basewp3). A human branch ending that way would collide with it, so\n// block it at creation time and steer the name back to the plain feature form.\nconst RESERVED_GENERATION_SUFFIX = /wp\\d+$/;\n\nfunction extractBranchName(command: string): string | null {\n    for (const pattern of BRANCH_PATTERNS) {\n        const m = pattern.exec(command);\n        if (m) return m[1];\n    }\n    return null;\n}\n\nfunction truncate(s: string): string {\n    const MAX = 120;\n    return s.length <= MAX ? s : s.slice(0, MAX) + '…';\n}\n\nfunction checkMainIsUpToDate(ctx: BashContext, requestedName: string): readonly Violation[] {\n    execSync('git fetch origin main --quiet', {\n        cwd: ctx.workspaceRoot,\n        encoding: 'utf8',\n    });\n    const countStr = execSync('git rev-list HEAD..origin/main --count', {\n        cwd: ctx.workspaceRoot,\n        encoding: 'utf8',\n    }).trim();\n    const count = parseInt(countStr, 10);\n    if (count > 0) {\n        return [new V(\n            1,\n            truncate(ctx.command),\n            `Local main is ${count} commit(s) behind origin/main. Run 'git pull origin main' first, then retry creating branch '${requestedName}'.`,\n        )];\n    }\n    return [];\n}\n\nexport class BranchCreationGuardRule extends BashRuleBase<BranchCreationGuardConfig> {\n    constructor(config: BranchCreationGuardConfig) { super(config, 'branch-creation-guard'); }\n\n    readonly description = 'Block new-branch creation when main is stale, or when branching off a non-main branch.';\n    override readonly defaultOptions = {\n        subBranchNaming: DEFAULT_SUB_BRANCH_NAMING,\n        branchFormat: DEFAULT_BRANCH_FORMAT,\n    };\n\n    private get branchFormat(): string {\n        return this.config.branchFormat ?? DEFAULT_BRANCH_FORMAT;\n    }\n\n    private get subBranchNaming(): string {\n        return this.config.subBranchNaming ?? DEFAULT_SUB_BRANCH_NAMING;\n    }\n\n    // Mode-aware fix hints. Branches off main follow branchFormat — never the sub-branch\n    // convention. The sub-branch affordance only appears under mode 'ON'; 'ON_NO_SUBBRANCHES'\n    // hard-blocks it and points instead at the ignoreModifiedUntilEpoch escape hatch.\n    get fixHint(): FixHint {\n        const options = [\n            new Option(\"Run 'git checkout main && git pull origin main', then create your branch FROM main\", true),\n            new Option(`Name a branch off main per branch-creation-guard.branchFormat: ${this.branchFormat}`),\n        ];\n        if (this.config.mode === 'ON_NO_SUBBRANCHES') {\n            options.push(new Option(\n                'Sub-branches (branching off another feature branch) are disabled. To temporarily allow one, set ' +\n                \"branch-creation-guard.ignoreModifiedUntilEpoch to a future epoch in webpieces.config.json\",\n            ));\n        } else {\n            options.push(new Option(\n                `If you truly need a stacked sub-branch (requires human approval), name it per branch-creation-guard.subBranchNaming: ${this.subBranchNaming}`,\n            ));\n        }\n        return new FixHint(\n            'Cannot create this branch (main is stale, or branching off a non-main branch).',\n            'Create your branch from an up-to-date main. Pick one:',\n            options,\n        );\n    }\n\n    check(ctx: BashContext): readonly Violation[] {\n        const requestedName = extractBranchName(ctx.command);\n        if (!requestedName) return [];\n\n        if (RESERVED_GENERATION_SUFFIX.test(requestedName)) {\n            return [new V(\n                1,\n                truncate(ctx.command),\n                `Branch name '${requestedName}' ends in 'wp<number>', which is reserved for the ` +\n                `squash-merge tool's generation marker (base → basewp2 → basewp3). ` +\n                `Rename it to a plain feature branch. ${this.branchFormat}.`,\n            )];\n        }\n\n        const currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {\n            cwd: ctx.workspaceRoot,\n            encoding: 'utf8',\n        }).trim();\n\n        if (currentBranch === 'main') {\n            return checkMainIsUpToDate(ctx, requestedName);\n        }\n\n        // Not on main: creating this branch would stack it on a feature branch (a sub-branch).\n        if (this.config.mode === 'ON_NO_SUBBRANCHES') {\n            return [new V(\n                1,\n                truncate(ctx.command),\n                `You are on '${currentBranch}', not main. You need to run ` +\n                `git checkout main && git pull && git checkout -b ${requestedName} ` +\n                `instead of branching from this branch!!! ${this.branchFormat}. ` +\n                `You can temporarily turn this off if you truly need a sub-branch by setting ` +\n                `branch-creation-guard.ignoreModifiedUntilEpoch (a future epoch) in webpieces.config.json.`,\n            )];\n        }\n\n        return [new V(\n            1,\n            truncate(ctx.command),\n            `You are on '${currentBranch}', not main. Branches must be created from main: ` +\n            `git checkout main && git pull && git checkout -b ${requestedName}. ${this.branchFormat}. ` +\n            `If you truly need a stacked sub-branch (requires human approval), name it per ` +\n            `branch-creation-guard.subBranchNaming ('${this.subBranchNaming}').`,\n        )];\n    }\n}\n"]}
+{"version":3,"file":"branch-creation-guard.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/ai-hook-rules/src/core/rules/branch-creation-guard.ts"],"names":[],"mappings":"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","sourcesContent":["import { execSync } from 'child_process';\n\nimport { BranchCreationGuardConfig } from '@webpieces/rules-config';\n\nimport type { BashContext, Violation } from '../types';\nimport { Violation as V } from '../types';\nimport { BashRuleBase } from '../rule-base';\nimport { FixHint, Option } from '../fix-hint';\n\n// Defaults used when the rule has no explicit value in webpieces.config.json.\n// branchFormat is a human sentence telling the AI how to name a branch created off main; it is\n// intentionally NOT the sub-branch convention (sub-branches are a separate, human-approved path).\nconst DEFAULT_BRANCH_FORMAT =\n    'Name it {whoami}/<short-feature-description> — lowercase, no version numbers, no sub/ prefix (e.g. dean/upgrade-webpieces)';\nconst DEFAULT_SUB_BRANCH_NAMING = 'feature/<ticket>/<short-description>';\n\nconst BRANCH_PATTERNS: RegExp[] = [\n    /git\\s+checkout\\s+-[bB]\\s+([^\\s]+)/,\n    /git\\s+switch\\s+-[cC]\\s+([^\\s]+)/,\n    /git\\s+branch\\s+(?!-[dDmMrRla])([^\\s-][^\\s]*)/,\n];\n\n// A trailing `wp<number>` was the old squash-merge generation marker (base → basewp2 → basewp3).\n// The tooling NO LONGER produces it — a sync now lands back on the same feature name — but the suffix\n// stays RESERVED so a human branch can't collide with a leftover `…wpN` still floating in a consumer\n// repo mid-transition. Block it at creation time and steer the name back to the plain feature form.\nconst RESERVED_GENERATION_SUFFIX = /wp\\d+$/;\n\nfunction extractBranchName(command: string): string | null {\n    for (const pattern of BRANCH_PATTERNS) {\n        const m = pattern.exec(command);\n        if (m) return m[1];\n    }\n    return null;\n}\n\nfunction truncate(s: string): string {\n    const MAX = 120;\n    return s.length <= MAX ? s : s.slice(0, MAX) + '…';\n}\n\nfunction checkMainIsUpToDate(ctx: BashContext, requestedName: string): readonly Violation[] {\n    execSync('git fetch origin main --quiet', {\n        cwd: ctx.workspaceRoot,\n        encoding: 'utf8',\n    });\n    const countStr = execSync('git rev-list HEAD..origin/main --count', {\n        cwd: ctx.workspaceRoot,\n        encoding: 'utf8',\n    }).trim();\n    const count = parseInt(countStr, 10);\n    if (count > 0) {\n        return [new V(\n            1,\n            truncate(ctx.command),\n            `Local main is ${count} commit(s) behind origin/main. Run 'git pull origin main' first, then retry creating branch '${requestedName}'.`,\n        )];\n    }\n    return [];\n}\n\nexport class BranchCreationGuardRule extends BashRuleBase<BranchCreationGuardConfig> {\n    constructor(config: BranchCreationGuardConfig) { super(config, 'branch-creation-guard'); }\n\n    readonly description = 'Block new-branch creation when main is stale, or when branching off a non-main branch.';\n    override readonly defaultOptions = {\n        subBranchNaming: DEFAULT_SUB_BRANCH_NAMING,\n        branchFormat: DEFAULT_BRANCH_FORMAT,\n    };\n\n    private get branchFormat(): string {\n        return this.config.branchFormat ?? DEFAULT_BRANCH_FORMAT;\n    }\n\n    private get subBranchNaming(): string {\n        return this.config.subBranchNaming ?? DEFAULT_SUB_BRANCH_NAMING;\n    }\n\n    // Mode-aware fix hints. Branches off main follow branchFormat — never the sub-branch\n    // convention. The sub-branch affordance only appears under mode 'ON'; 'ON_NO_SUBBRANCHES'\n    // hard-blocks it and points instead at the ignoreModifiedUntilEpoch escape hatch.\n    get fixHint(): FixHint {\n        const options = [\n            new Option(\"Run 'git checkout main && git pull origin main', then create your branch FROM main\", true),\n            new Option(`Name a branch off main per branch-creation-guard.branchFormat: ${this.branchFormat}`),\n        ];\n        if (this.config.mode === 'ON_NO_SUBBRANCHES') {\n            options.push(new Option(\n                'Sub-branches (branching off another feature branch) are disabled. To temporarily allow one, set ' +\n                \"branch-creation-guard.ignoreModifiedUntilEpoch to a future epoch in webpieces.config.json\",\n            ));\n        } else {\n            options.push(new Option(\n                `If you truly need a stacked sub-branch (requires human approval), name it per branch-creation-guard.subBranchNaming: ${this.subBranchNaming}`,\n            ));\n        }\n        return new FixHint(\n            'Cannot create this branch (main is stale, or branching off a non-main branch).',\n            'Create your branch from an up-to-date main. Pick one:',\n            options,\n        );\n    }\n\n    check(ctx: BashContext): readonly Violation[] {\n        const requestedName = extractBranchName(ctx.command);\n        if (!requestedName) return [];\n\n        if (RESERVED_GENERATION_SUFFIX.test(requestedName)) {\n            return [new V(\n                1,\n                truncate(ctx.command),\n                `Branch name '${requestedName}' ends in 'wp<number>', which is reserved for the ` +\n                `squash-merge tool's generation marker (base → basewp2 → basewp3). ` +\n                `Rename it to a plain feature branch. ${this.branchFormat}.`,\n            )];\n        }\n\n        const currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {\n            cwd: ctx.workspaceRoot,\n            encoding: 'utf8',\n        }).trim();\n\n        if (currentBranch === 'main') {\n            return checkMainIsUpToDate(ctx, requestedName);\n        }\n\n        // Not on main: creating this branch would stack it on a feature branch (a sub-branch).\n        if (this.config.mode === 'ON_NO_SUBBRANCHES') {\n            return [new V(\n                1,\n                truncate(ctx.command),\n                `You are on '${currentBranch}', not main. You need to run ` +\n                `git checkout main && git pull && git checkout -b ${requestedName} ` +\n                `instead of branching from this branch!!! ${this.branchFormat}. ` +\n                `You can temporarily turn this off if you truly need a sub-branch by setting ` +\n                `branch-creation-guard.ignoreModifiedUntilEpoch (a future epoch) in webpieces.config.json.`,\n            )];\n        }\n\n        return [new V(\n            1,\n            truncate(ctx.command),\n            `You are on '${currentBranch}', not main. Branches must be created from main: ` +\n            `git checkout main && git pull && git checkout -b ${requestedName}. ${this.branchFormat}. ` +\n            `If you truly need a stacked sub-branch (requires human approval), name it per ` +\n            `branch-creation-guard.subBranchNaming ('${this.subBranchNaming}').`,\n        )];\n    }\n}\n"]}