@openagentsy/hooks 0.0.0-stage → 0.2.0

package/dist/registry.test.js

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import { BLOCK_PRIORITY, createOaRegistry, orderRules, run } from './registry.js';
+/** A rule that records that it ran and lets the call through. */
+function recording(id, ran, options = {}) {
+    return {
+        id,
+        event: 'PreToolCall',
+        handler: () => {
+            ran.push(id);
+            return { continue: true };
+        },
+        ...options,
+    };
+}
+describe('the registry', () => {
+    it('runs the blocking rules first, then the priority, then the order they were written', () => {
+        const ran = [];
+        const rules = [
+            recording('plain', ran),
+            recording('blocking', ran, { block: true }),
+            recording('high', ran, { priority: 10 }),
+            recording('low', ran, { priority: 1 }),
+            recording('second-plain', ran),
+        ];
+        expect(orderRules(rules).map((rule) => rule.id)).toEqual([
+            'blocking',
+            'high',
+            'low',
+            'plain',
+            'second-plain',
+        ]);
+    });
+    it('puts a blocking rule above a rule with a higher priority', () => {
+        const ran = [];
+        const rules = [
+            recording('high', ran, { priority: BLOCK_PRIORITY * 10 }),
+            recording('blocking', ran, { block: true }),
+        ];
+        expect(orderRules(rules).map((rule) => rule.id)).toEqual(['blocking', 'high']);
+    });
+    it('stops the chain at the first rule that stops it and keeps the reason', async () => {
+        const ran = [];
+        const rules = [
+            {
+                id: 'first',
+                event: 'PreToolCall',
+                handler: () => {
+                    ran.push('first');
+                    return { continue: true };
+                },
+            },
+            {
+                id: 'second',
+                event: 'PreToolCall',
+                handler: () => {
+                    ran.push('second');
+                    return { continue: false, reason: 'the reason' };
+                },
+            },
+            {
+                id: 'third',
+                event: 'PreToolCall',
+                handler: () => {
+                    ran.push('third');
+                    return { continue: true };
+                },
+            },
+        ];
+        const result = await run('PreToolCall', rules, {});
+        expect(result.continue).toBe(false);
+        expect(result.reasons).toEqual(['the reason']);
+        expect(ran).toEqual(['first', 'second']);
+    });
+    it('returns the transforms in order and lets the call through', async () => {
+        const rules = [
+            { id: 'a', event: 'PreToolCall', handler: () => ({ transform: { a: 1 } }) },
+            { id: 'b', event: 'PreToolCall', handler: () => ({ transform: { b: 2 } }) },
+        ];
+        const result = await run('PreToolCall', rules, {});
+        expect(result.continue).toBe(true);
+        expect(result.transformed).toEqual([{ a: 1 }, { b: 2 }]);
+    });
+    it('runs only the rules of the moment', async () => {
+        const ran = [];
+        const rules = [
+            recording('before', ran),
+            { ...recording('after', ran), event: 'PostToolCall' },
+        ];
+        await run('PreToolCall', rules, {});
+        expect(ran).toEqual(['before']);
+    });
+    it('runs a rule only for the roles it names', async () => {
+        const ran = [];
+        const rules = [recording('builders', ran, { roles: ['builder'] })];
+        await run('PreToolCall', rules, { role: 'lead' });
+        expect(ran).toEqual([]);
+        await run('PreToolCall', rules, { role: 'builder' });
+        expect(ran).toEqual(['builders']);
+    });
+    it('runs a scoped rule for nobody when the role is unknown', async () => {
+        const ran = [];
+        const rules = [recording('builders', ran, { roles: ['builder'] })];
+        await run('PreToolCall', rules, {});
+        expect(ran).toEqual([]);
+    });
+    it('gives the registry the rules in the order they run', () => {
+        const ran = [];
+        const registry = createOaRegistry([
+            recording('plain', ran),
+            recording('blocking', ran, { block: true }),
+        ]);
+        expect(registry.rules().map((rule) => rule.id)).toEqual(['blocking', 'plain']);
+        expect(registry.rules('PreToolCall').map((rule) => rule.id)).toEqual(['blocking', 'plain']);
+        expect(registry.rules('PostToolCall')).toEqual([]);
+    });
+});
+//# sourceMappingURL=registry.test.js.map

package/dist/registry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.test.js","sourceRoot":"","sources":["../src/registry.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAa,GAAG,EAAE,MAAM,eAAe,CAAC;AAE7F,iEAAiE;AACjE,SAAS,SAAS,CAAC,EAAU,EAAE,GAAa,EAAE,UAAyB,EAAE;IACvE,OAAO;QACL,EAAE;QACF,KAAK,EAAE,aAAa;QACpB,OAAO,EAAE,GAAG,EAAE;YACZ,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACb,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC5B,CAAC;QACD,GAAG,OAAO;KACX,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC5B,EAAE,CAAC,oFAAoF,EAAE,GAAG,EAAE;QAC5F,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG;YACZ,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC;YACvB,SAAS,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YAC3C,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;YACxC,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;YACtC,SAAS,CAAC,cAAc,EAAE,GAAG,CAAC;SAC/B,CAAC;QACF,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YACvD,UAAU;YACV,MAAM;YACN,KAAK;YACL,OAAO;YACP,cAAc;SACf,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAClE,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG;YACZ,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,cAAc,GAAG,EAAE,EAAE,CAAC;YACzD,SAAS,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;SAC5C,CAAC;QACF,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IACjF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sEAAsE,EAAE,KAAK,IAAI,EAAE;QACpF,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,KAAK,GAAW;YACpB;gBACE,EAAE,EAAE,OAAO;gBACX,KAAK,EAAE,aAAa;gBACpB,OAAO,EAAE,GAAG,EAAE;oBACZ,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBAClB,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;gBAC5B,CAAC;aACF;YACD;gBACE,EAAE,EAAE,QAAQ;gBACZ,KAAK,EAAE,aAAa;gBACpB,OAAO,EAAE,GAAG,EAAE;oBACZ,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;oBACnB,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;gBACnD,CAAC;aACF;YACD;gBACE,EAAE,EAAE,OAAO;gBACX,KAAK,EAAE,aAAa;gBACpB,OAAO,EAAE,GAAG,EAAE;oBACZ,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBAClB,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;gBAC5B,CAAC;aACF;SACF,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACnD,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;QAC/C,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,MAAM,KAAK,GAAW;YACpB,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE;YAC3E,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE;SAC5E,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACnD,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,KAAK,IAAI,EAAE;QACjD,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG;YACZ,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC;YACxB,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,cAAuB,EAAE;SAC/D,CAAC;QACF,MAAM,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;QACvD,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,SAAS,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;QACnE,MAAM,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACxB,MAAM,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QACrD,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;QACtE,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,SAAS,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;QACnE,MAAM,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,gBAAgB,CAAC;YAChC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC;YACvB,SAAS,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;SAC5C,CAAC,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;QAC/E,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;QAC5F,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/rules.d.ts

@@ -0,0 +1,107 @@
+import { type PreToolCallEvent } from './event.js';
+import { type QualityRuleOptions } from './quality/rule.js';
+import type { Rule } from './registry.js';
+/**
+ * The command, split into tokens.
+ *
+ * A quoted span is one token, so a command that is passed as a quoted
+ * argument stays one thing: `bash -c "git commit -n"` is three tokens and
+ * the third one holds the command. The quotes are kept, so the caller can
+ * tell a value from an argument.
+ */
+export declare function tokenise(command: string): string[];
+/**
+ * The command, split into the segments a separator ends.
+ *
+ * A separator inside a quoted span does not end a segment: the span is one
+ * argument, and a command in it belongs to the command that holds the
+ * argument.
+ */
+export declare function commandSegments(command: string): string[];
+/**
+ * The payload of every substitution in a command.
+ *
+ * The shell runs a substitution before the command that holds it, so the
+ * payload is a command of its own: `git commit -m "$(rm -rf /)"` removes
+ * the directory even though the message is only text.
+ */
+export declare function substitutionPayloads(command: string): string[];
+/**
+ * The scope of the shell matcher.
+ *
+ * It covers: the flags of a removal in any order and either spelling, the
+ * git commands that skip the hooks, the other package managers, and the
+ * payload of every quoted span and every substitution, which is scanned as
+ * a command of its own.
+ *
+ * It does not cover: the shell. A payload behind a construct this matcher
+ * does not read - an alias, a function, a here-document, a variable - is
+ * not seen. A name the matcher does not know is treated as a writer, not
+ * as a reader.
+ */
+export declare function scannedParts(command: string): string[];
+/**
+ * Whether a command skips the git hooks.
+ *
+ * The `-n` of `git commit` is the short form of `--no-verify`, and it is
+ * caught in any position of the commit's own arguments:
+ * `git commit -n`, `git commit -m "wip" -n`, `git commit -a -n` and
+ * `git commit -nm "wip"` all skip the hooks. A command that is passed as a
+ * quoted argument is read too, so `bash -c "git commit -n"` is caught.
+ */
+export declare function skipsGitHooks(command: string): boolean;
+/**
+ * Whether a path is one a person changes.
+ *
+ * The path is compared on its segments, so a directory is a directory
+ * whether or not the path names it with a trailing slash, and a file is a
+ * file wherever it sits. A delete or a move that names the directory
+ * itself is caught as well.
+ */
+export declare function isProtected(path: string): boolean;
+/**
+ * Whether a command destroys something.
+ *
+ * The command is read in parts, so a destructive command inside a
+ * substitution or inside a quoted argument is still one: `echo $(rm -rf
+ * /)` and `bash -c "rm -rf /"` are both caught. The flags of a removal
+ * are read per part, so `rm -r build; rm -f /tmp/x` is two removals and
+ * neither is the dangerous one.
+ */
+export declare function isDestructiveCommand(command: string): boolean;
+/**
+ * Whether a command uses another package manager.
+ */
+export declare function usesOtherPackageManager(command: string): boolean;
+/**
+ * The text a call would write.
+ *
+ * The host puts the content in the arguments: a write carries `content`,
+ * an edit carries `newString`, and a patch carries the whole patch. A
+ * patch is read for the lines it adds, so a secret in the text that is
+ * being added is found.
+ */
+export declare function contentOf(event: PreToolCallEvent): string;
+/** The options the default rules are built with. */
+export interface DefaultRuleOptions {
+    /** The workspace root: the project the agent works in. */
+    workspace: string;
+    /** The state root: where the `.openagentsy/` directory lives. */
+    stateRoot: string;
+    /** The home directory the worktrees live under; the home of the user by default. */
+    home?: string;
+    /**
+     * The quality check, when the project runs one.
+     *
+     * A project that names no mode runs no check, so the rule is left out
+     * rather than registered and idle.
+     */
+    quality?: Omit<QualityRuleOptions, 'workspace' | 'stateRoot'>;
+}
+/**
+ * The seven default rules.
+ *
+ * They run in the order they are written, and every one of them blocks.
+ */
+export declare const defaultRules: ({ workspace, stateRoot, home, quality, }: DefaultRuleOptions) => Rule[];
+//# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAGA,OAAO,EAA+B,KAAK,gBAAgB,EAAmB,MAAM,YAAY,CAAC;AAEjG,OAAO,EAAE,KAAK,kBAAkB,EAAqB,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAiB,IAAI,EAAE,MAAM,eAAe,CAAC;AA+CzD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAElD;AAqCD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAIzD;AAoCD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAU9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAStD;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEtD;AAmGD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAYjD;AA8ED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE7D;AAYD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAWzD;AA+CD,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,GAAG,WAAW,CAAC,CAAC;CAC/D;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,0CAK1B,kBAAkB,KAAG,IAAI,EAwH3B,CAAC"}