@juanem1/pi-git 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.2.0]
4
+
5
+ - Add `--git-allow` / `PI_GIT_ALLOW` to pre-authorize specific mutations
6
+ (`commit`, `push`, `worktree_add`, `worktree_remove`, `worktree_prune`) for
7
+ RPC and CI runs. Nothing is pre-authorized by default, and invalid values block
8
+ mutations.
9
+ - In RPC mode, a refused confirmation now says that the user may have declined or
10
+ the client may have dismissed the dialog without asking anyone. It also
11
+ points to `--git-allow` and sends a `notify` warning to the client.
12
+
3
13
  ## [0.1.0]
4
14
 
5
15
  - Initial release: `git_status`, `git_diff`, `git_log`, `git_show`, `git_commit`,
package/README.md CHANGED
@@ -1,7 +1,8 @@
1
1
  # Package pi-git
2
2
 
3
3
  A Pi package for Git, with no npm dependencies or installation scripts.
4
- Commits, pushes, and worktree changes require individual confirmation.
4
+ Commits, pushes, and worktree changes require individual confirmation, unless
5
+ the person running Pi pre-authorizes them (see [Runs without a person](#runs-without-a-person-rpc-and-ci)).
5
6
  It does not add co-authors or impose a commit message format.
6
7
 
7
8
  ## Requirements
@@ -71,11 +72,42 @@ Other already-staged files are excluded from the commit.
71
72
  the main, current, or locked worktrees.
72
73
  - Push requires an explicit remote with a single HTTPS/SSH URL. It does not
73
74
  accept local paths, remote helpers, tags, or refspecs from the model.
74
- - Mutations are rejected without a Pi confirmation interface.
75
+ - Mutations are rejected without a Pi confirmation interface, unless they are
76
+ pre-authorized with `--git-allow` or `PI_GIT_ALLOW`. Nothing is pre-authorized
77
+ by default.
78
+ - In RPC mode (`pi --mode rpc`) Pi reports an interface and sends each
79
+ confirmation to the client as an `extension_ui_request` (`method: "confirm"`).
80
+ Pi turns a `cancelled: true` response into the same `false` as an explicit
81
+ "No", so the extension cannot tell them apart. In RPC mode a refusal says so,
82
+ and the client also gets a `notify` warning.
75
83
  - Does not disable hooks or configured signing. Git hooks, filters, and transports
76
84
  can run programs from the repository or environment: use trusted repositories
77
85
  and Git configurations.
78
86
 
87
+ ### Runs without a person (RPC and CI)
88
+
89
+ A client with nobody to answer the dialogs can pre-authorize specific mutations
90
+ for the whole run, with a comma-separated list:
91
+
92
+ ```sh
93
+ pi --mode rpc --git-allow commit
94
+ PI_GIT_ALLOW=commit,push pi -p "..."
95
+ ```
96
+
97
+ Accepted values: `commit`, `push`, `worktree_add`, `worktree_remove`,
98
+ `worktree_prune`. There is no `all`. An unknown value, or `--git-allow` without
99
+ a value, blocks every mutation with an error. If both are set, `--git-allow`
100
+ wins over `PI_GIT_ALLOW`, so `--git-allow ""` turns the variable off.
101
+ Authorizing `commit` does not authorize `push` or any worktree change.
102
+
103
+ Pre-authorization only skips the dialog. Every other check still runs: explicit
104
+ files, branch rechecks, HTTPS/SSH remotes only, and clean worktrees only. When
105
+ there is an interface, each pre-authorized mutation sends an `info`
106
+ notification with the same details as the dialog. The model cannot turn it on
107
+ from the session: the flag and the environment variable are read from the Pi
108
+ process. A variable left in your shell profile also applies to interactive
109
+ sessions.
110
+
79
111
  This **is not a sandbox** and does not block Pi's general Bash access or other
80
112
  extensions. Queries disable external diff, textconv, and signature verification.
81
113
  Large outputs are explicitly limited; a process that exceeds 120 seconds or
package/extensions/git.js CHANGED
@@ -1,4 +1,4 @@
1
- import { createGitOperations } from "../src/git.js";
1
+ import { AUTHORIZABLE, createGitOperations, parseAuthorizations, runGit } from "../src/git.js";
2
2
 
3
3
  const string = (description) => ({ type: "string", minLength: 1, description });
4
4
  const paths = {
@@ -10,7 +10,14 @@ const paths = {
10
10
  const ref = string("Git revision or range, never a command-line option.");
11
11
 
12
12
  export default function (pi) {
13
- const operations = createGitOperations();
13
+ pi.registerFlag("git-allow", {
14
+ type: "string",
15
+ description: `Pre-authorize Git mutations without confirmation, comma-separated: ${AUTHORIZABLE.join(", ")}. Overrides PI_GIT_ALLOW.`,
16
+ });
17
+ // Read on every mutation so an invalid value fails that mutation loudly instead of loading silently.
18
+ const operations = createGitOperations(runGit, () => parseAuthorizations(
19
+ pi.getFlag("git-allow") ?? process.env.PI_GIT_ALLOW,
20
+ ));
14
21
  const register = (name, description, properties = {}, required = [], mutating = false) => {
15
22
  pi.registerTool({
16
23
  name,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@juanem1/pi-git",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Focused Git tools for Pi with explicit confirmation for mutations.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -13,13 +13,25 @@
13
13
  "bugs": {
14
14
  "url": "https://github.com/juanem1/pi-git/issues"
15
15
  },
16
- "keywords": ["pi-package", "pi", "git"],
16
+ "keywords": [
17
+ "pi-package",
18
+ "pi",
19
+ "git"
20
+ ],
17
21
  "engines": {
18
22
  "node": ">=22"
19
23
  },
20
- "files": ["extensions", "src", "README.md", "CHANGELOG.md", "LICENSE"],
24
+ "files": [
25
+ "extensions",
26
+ "src",
27
+ "README.md",
28
+ "CHANGELOG.md",
29
+ "LICENSE"
30
+ ],
21
31
  "pi": {
22
- "extensions": ["./extensions/git.js"]
32
+ "extensions": [
33
+ "./extensions/git.js"
34
+ ]
23
35
  },
24
36
  "publishConfig": {
25
37
  "access": "public",
package/src/git.js CHANGED
@@ -118,18 +118,55 @@ function inside(path, parent) {
118
118
  return !rest || (!isAbsolute(rest) && rest !== ".." && !rest.startsWith(`..${sep}`));
119
119
  }
120
120
 
121
- async function confirm(ctx, signal, title, description) {
121
+ export const AUTHORIZABLE = ["commit", "push", "worktree_add", "worktree_remove", "worktree_prune"];
122
+
123
+ // Parses the --git-allow / PI_GIT_ALLOW value: a comma-separated list of AUTHORIZABLE operations.
124
+ // Anything else (including a bare flag without a value) is an error, so a typo never widens access.
125
+ export function parseAuthorizations(value) {
126
+ if (value === undefined || value === null || value === "") {
127
+ return new Set();
128
+ }
129
+ if (typeof value !== "string") {
130
+ throw new Error(`--git-allow needs a value: a comma-separated list of ${AUTHORIZABLE.join(", ")}.`);
131
+ }
132
+ const items = value.split(",").map((item) => item.trim()).filter(Boolean);
133
+ for (const item of items) {
134
+ if (!AUTHORIZABLE.includes(item)) {
135
+ throw new Error(
136
+ `Unknown --git-allow operation ${JSON.stringify(item)}; use a comma-separated list of ${AUTHORIZABLE.join(", ")}. No changes were made.`,
137
+ );
138
+ }
139
+ }
140
+ return new Set(items);
141
+ }
142
+
143
+ async function confirm(ctx, signal, authorizations, operation, title, description) {
122
144
  signal?.throwIfAborted();
145
+ if (authorizations().has(operation)) {
146
+ if (ctx.hasUI) {
147
+ ctx.ui.notify?.(`${title}: pre-authorized by --git-allow ${operation}.\n${description}`, "info");
148
+ }
149
+ return;
150
+ }
151
+ const hint = `A run without a person to answer can pre-authorize it with --git-allow ${operation}.`;
123
152
  if (!ctx.hasUI) {
124
- throw new Error("Interactive confirmation is required; no changes were made.");
153
+ throw new Error(`Interactive confirmation is required; no changes were made. ${hint}`);
125
154
  }
126
155
  if (!await ctx.ui.confirm(title, description)) {
156
+ if (ctx.mode === "rpc") {
157
+ // Pi maps an RPC client's `cancelled` response to `false`, the same as an explicit "No".
158
+ ctx.ui.notify?.(`pi-git: "${title}" was not confirmed; nothing changed. ${hint}`, "warning");
159
+ throw new Error(
160
+ "Not confirmed: the user declined, or the RPC client dismissed the dialog without asking anyone; "
161
+ + `no changes were made. ${hint}`,
162
+ );
163
+ }
127
164
  throw new Error("Cancelled; no changes were made.");
128
165
  }
129
166
  signal?.throwIfAborted();
130
167
  }
131
168
 
132
- export function createGitOperations(run = runGit) {
169
+ export function createGitOperations(run = runGit, authorizations = () => new Set()) {
133
170
  const root = async (ctx, signal) => realpath(
134
171
  (await run(["rev-parse", "--show-toplevel"], ctx.cwd, signal)).replace(/\r?\n$/, ""),
135
172
  );
@@ -249,7 +286,7 @@ export function createGitOperations(run = runGit) {
249
286
  const cwd = await root(ctx, signal);
250
287
  const expected = await branch(cwd, signal);
251
288
  await validateFiles(selected, cwd, signal, run);
252
- await confirm(ctx, signal, "Confirm Git commit",
289
+ await confirm(ctx, signal, authorizations, "commit", "Confirm Git commit",
253
290
  `Repository: ${JSON.stringify(cwd)}\nBranch: ${JSON.stringify(expected)}\n`
254
291
  + `Files: ${JSON.stringify(selected)}\nMessage: ${JSON.stringify(params.message)}\n\n`
255
292
  + "Commit the complete working-tree contents of these files only. No push or automatic coauthors.\n"
@@ -282,7 +319,7 @@ export function createGitOperations(run = runGit) {
282
319
  const expected = await branch(cwd, signal);
283
320
  const sha = await commitId("HEAD", cwd, signal);
284
321
  const url = await pushUrl(params.remote, cwd, signal);
285
- await confirm(ctx, signal, "Confirm Git push",
322
+ await confirm(ctx, signal, authorizations, "push", "Confirm Git push",
286
323
  `Repository: ${JSON.stringify(cwd)}\nRemote: ${JSON.stringify(params.remote)}\n`
287
324
  + `Destination: ${JSON.stringify(url)}\nBranch: ${JSON.stringify(expected)}\nCommit: ${sha}\n\n`
288
325
  + "Publish only this commit to the same branch name. No force, tags, deletion, or upstream changes.");
@@ -332,7 +369,7 @@ export function createGitOperations(run = runGit) {
332
369
  throw new Error("Branch already exists; omit base.");
333
370
  }
334
371
  const base = exists ? undefined : await commitId(params.base ?? "HEAD", cwd, signal);
335
- await confirm(ctx, signal, "Confirm worktree creation",
372
+ await confirm(ctx, signal, authorizations, "worktree_add", "Confirm worktree creation",
336
373
  `Repository: ${JSON.stringify(cwd)}\nDestination: ${JSON.stringify(target)}\n`
337
374
  + `Branch: ${JSON.stringify(name)} (${exists ? "existing" : `new from ${base}`})\n\n`
338
375
  + "Create a separate worktree. The current worktree stays on its current branch.");
@@ -351,7 +388,7 @@ export function createGitOperations(run = runGit) {
351
388
  const cwd = await root(ctx, signal);
352
389
  const target = await realpath(resolve(cwd, params.path));
353
390
  await removable(target, cwd, ctx, signal);
354
- await confirm(ctx, signal, "Confirm worktree removal",
391
+ await confirm(ctx, signal, authorizations, "worktree_remove", "Confirm worktree removal",
355
392
  `Repository: ${JSON.stringify(cwd)}\nWorktree: ${JSON.stringify(target)}\n\n`
356
393
  + "Remove this clean worktree directory. Keep its branch. Never force removal.");
357
394
  await removable(target, cwd, ctx, signal);
@@ -366,7 +403,7 @@ export function createGitOperations(run = runGit) {
366
403
  if (!preview.trim()) {
367
404
  return "No stale worktree metadata to prune.";
368
405
  }
369
- await confirm(ctx, signal, "Confirm worktree metadata pruning",
406
+ await confirm(ctx, signal, authorizations, "worktree_prune", "Confirm worktree metadata pruning",
370
407
  `Repository: ${JSON.stringify(cwd)}\nPreview: ${JSON.stringify(preview)}\n\n`
371
408
  + "Remove stale administrative records only, using Git's default expiration. No directory deletion.");
372
409
  if (await dryRun() !== preview) {