@blogic-cz/agent-tools 1.0.0 → 1.1.0

package/README.md

@@ -282,6 +282,18 @@ Two optional scope guards sit on top. A profile keyed `prod`/`production`, or ca
 
 `azdo-tool` keeps its allowlist of read-only operations (`list`, `run`, `show`, `show-tags`) and rejects `create`/`delete`/`update`/`cancel`/`queue` anywhere in the command. `run` is accepted only in the `pipelines` group — `acr run` and `acr task run` execute arbitrary commands in Azure and are blocked. The `acr` and `account` groups remain reachable from `azdo-tool` for backwards compatibility; new work should use `az-tool` for them. Because those two groups address the Azure platform rather than Azure DevOps, the platform credential rules apply to them here as well — `acr credential show` is refused by both tools. The verb and segment lists behind that live in `src/shared/azure-credentials.ts` so the two tools cannot drift apart.
 
+### Gist commands
+
+```bash
+bun gh-tool gist list
+bun gh-tool gist view --id <gist-id>
+bun gh-tool gist create --body "snippet" --filename example.txt
+bun gh-tool gist edit --id <gist-id> --body "updated" --filename example.txt
+bun gh-tool gist delete --id <gist-id> --confirm
+```
+
+Gists are secret by default. `gist delete` prints a dry run unless `--confirm` is passed. `gist edit` requires a content or mutation flag and never opens an editor.
+
 ### gh-tool machine contracts
 
 `pr view` adds `headSha` and `baseSha`; failed-check evidence adds the same SHA pair. Review summaries, inline comments, and threads add `commitSha` plus `feedbackOrigin`: `current_head` only for an exact `commitSha === headSha`, `pre_existing` for a different known SHA (not an obsolescence verdict), and `unknown` when either SHA is absent. Issue comments always use `commitSha: null` and `feedbackOrigin: unknown`. `review-triage` preserves existing fields and adds `inlineComments` plus per-kind `feedbackOriginCounts`; batch triage returns the same object per PR. `pr request-review --reviewers alice,bob` emits sorted `submittedReviewers` (normalized input), `newlyRequested` and `alreadyPending` (the submitted logins split by whether a pending request already existed, so a fresh re-request is distinguishable from a no-op), and `requestedReviewers` (GitHub-confirmed result). `pr last-human-reviewer` derives `currentRequestedReviewers` from live `reviewRequests` only; timeline events are not replayed because GitHub clears a pending request on review submit without emitting `ReviewRequestRemovedEvent`.

package/dist/gh-tool/gist.d.ts

@@ -0,0 +1,102 @@
+import { Command } from "effect/unstable/cli";
+import { Effect, Option } from "effect";
+import { GitHubCommandError } from "./errors";
+import { GitHubService } from "./service";
+type GistApiFile = {
+    filename: string;
+    language: string | null;
+    type: string;
+    size: number;
+    truncated?: boolean;
+    content?: string;
+};
+type GistApi = {
+    id: string;
+    description: string | null;
+    public: boolean;
+    html_url: string;
+    created_at: string;
+    updated_at: string;
+    owner: {
+        login: string;
+    } | null;
+    files: Record<string, GistApiFile>;
+};
+type GistFile = {
+    filename: string;
+    language: string | null;
+    size: number;
+    truncated: boolean;
+    content?: string;
+};
+type GistDetail = {
+    id: string;
+    description: string | null;
+    public: boolean;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+    owner: string | null;
+    files: GistFile[];
+};
+type GistCreateResult = {
+    created: true;
+    id: string;
+    url: string;
+    public: boolean;
+    files: string[];
+};
+export declare const toGistDetail: (gist: GistApi, opts: {
+    filename: string | null;
+    withContent: boolean;
+}) => GistDetail;
+export declare const validateBodyFilename: (body: string | null, filename: string | null, command: string) => GitHubCommandError | null;
+export declare const validateEditInput: (opts: {
+    body: string | null;
+    filename: string | null;
+    description: string | null;
+    add: string | null;
+    remove: string | null;
+}) => GitHubCommandError | null;
+export declare const createGist: (opts: {
+    paths: string[];
+    description: string | null;
+    public: boolean;
+}) => Effect.Effect<GistCreateResult, GitHubCommandError | import("./errors").GitHubNotFoundError | import("./errors").GitHubAuthError, GitHubService>;
+export declare const gistListCommand: Command.Command<"list", {
+    readonly format: "json" | "toon";
+    readonly limit: number;
+    readonly visibility: Option.Option<"public" | "secret">;
+}, {}, GitHubCommandError | import("./errors").GitHubNotFoundError | import("./errors").GitHubAuthError, GitHubService>;
+export declare const gistViewCommand: Command.Command<"view", {
+    readonly filename: Option.Option<string>;
+    readonly format: "json" | "toon";
+    readonly id: string;
+    readonly metadataOnly: boolean;
+}, {}, GitHubCommandError | import("./errors").GitHubNotFoundError | import("./errors").GitHubAuthError, GitHubService>;
+export declare const gistCreateCommand: Command.Command<"create", {
+    readonly body: Option.Option<string>;
+    readonly bodyFile: Option.Option<string>;
+    readonly desc: Option.Option<string>;
+    readonly filename: Option.Option<string>;
+    readonly files: Option.Option<string>;
+    readonly format: "json" | "toon";
+    readonly public: boolean;
+}, {}, GitHubCommandError | import("./errors").GitHubNotFoundError | import("./errors").GitHubAuthError, GitHubService>;
+export declare const gistEditCommand: Command.Command<"edit", {
+    readonly add: Option.Option<string>;
+    readonly body: Option.Option<string>;
+    readonly bodyFile: Option.Option<string>;
+    readonly desc: Option.Option<string>;
+    readonly filename: Option.Option<string>;
+    readonly format: "json" | "toon";
+    readonly id: string;
+    readonly remove: Option.Option<string>;
+}, {}, GitHubCommandError | import("./errors").GitHubNotFoundError | import("./errors").GitHubAuthError, GitHubService>;
+export declare const gistDeleteCommand: Command.Command<"delete", {
+    readonly confirm: boolean;
+    readonly format: "json" | "toon";
+    readonly id: string;
+}, {}, GitHubCommandError | import("./errors").GitHubNotFoundError | import("./errors").GitHubAuthError, GitHubService>;
+export {};
+//# sourceMappingURL=gist.d.ts.map

package/dist/gh-tool/gist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gist.d.ts","sourceRoot":"","sources":["../../src/gh-tool/gist.ts"],"names":[],"mappings":"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"}

package/dist/gh-tool/text-input.d.ts

@@ -1,6 +1,7 @@
 import { Effect, Schema } from "effect";
 import { GitHubCommandError } from "#gh/errors";
 declare const MissingMode: Schema.Literals<readonly ["error", "null", "default"]>;
+export declare const isSensitivePath: (filePath: string) => boolean;
 type ResolveTextInputOptions = {
     command: string;
     value: string | null;

package/dist/gh-tool/text-input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text-input.d.ts","sourceRoot":"","sources":["../../src/gh-tool/text-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIhD,QAAA,MAAM,WAAW,wDAAgD,CAAC;AAoBlE,KAAK,uBAAuB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,WAAW,CAAC,CAAC;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAsFF,eAAO,MAAM,wBAAwB,GACnC,SAAS,IAAI,CAAC,uBAAuB,EAAE,aAAa,GAAG,cAAc,CAAC,KACrE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAIuD,CAAC;AAEnG,eAAO,MAAM,wBAAwB,GACnC,SAAS,IAAI,CAAC,uBAAuB,EAAE,aAAa,GAAG,cAAc,CAAC,KACrE,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,kBAAkB,CAI9C,CAAC;AAEL,eAAO,MAAM,uBAAuB,GAClC,SAAS,IAAI,CAAC,uBAAuB,EAAE,aAAa,GAAG,cAAc,CAAC,GAAG;IACvE,YAAY,EAAE,MAAM,CAAC;CACtB,KACA,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAKsD,CAAC"}
+{"version":3,"file":"text-input.d.ts","sourceRoot":"","sources":["../../src/gh-tool/text-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAShD,QAAA,MAAM,WAAW,wDAAgD,CAAC;AAIlE,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,YACmB,CAAC;AAkBpE,KAAK,uBAAuB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,WAAW,CAAC,CAAC;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAsFF,eAAO,MAAM,wBAAwB,GACnC,SAAS,IAAI,CAAC,uBAAuB,EAAE,aAAa,GAAG,cAAc,CAAC,KACrE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAIuD,CAAC;AAEnG,eAAO,MAAM,wBAAwB,GACnC,SAAS,IAAI,CAAC,uBAAuB,EAAE,aAAa,GAAG,cAAc,CAAC,KACrE,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,kBAAkB,CAI9C,CAAC;AAEL,eAAO,MAAM,uBAAuB,GAClC,SAAS,IAAI,CAAC,uBAAuB,EAAE,aAAa,GAAG,cAAc,CAAC,GAAG;IACvE,YAAY,EAAE,MAAM,CAAC;CACtB,KACA,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAKsD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure platform, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",

package/src/gh-tool/gist.ts

@@ -0,0 +1,625 @@
+import { Command, Flag } from "effect/unstable/cli";
+import { Effect, Option } from "effect";
+import { join } from "node:path";
+
+import { formatOption, logFormatted } from "#shared";
+import { isSensitivePath, resolveOptionalTextInput } from "#gh/text-input";
+import { GitHubCommandError } from "./errors";
+import { GitHubService } from "./service";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+// `gh gist list/view` have no --json, so reads go through `gh api gists` (REST shape).
+type GistApiFile = {
+  filename: string;
+  language: string | null;
+  type: string;
+  size: number;
+  truncated?: boolean;
+  content?: string;
+};
+
+type GistApi = {
+  id: string;
+  description: string | null;
+  public: boolean;
+  html_url: string;
+  created_at: string;
+  updated_at: string;
+  owner: { login: string } | null;
+  files: Record<string, GistApiFile>;
+};
+
+type GistListItem = {
+  id: string;
+  description: string | null;
+  public: boolean;
+  url: string;
+  createdAt: string;
+  updatedAt: string;
+  files: string[];
+};
+
+type GistFile = {
+  filename: string;
+  language: string | null;
+  size: number;
+  truncated: boolean;
+  content?: string;
+};
+
+type GistDetail = {
+  id: string;
+  description: string | null;
+  public: boolean;
+  url: string;
+  createdAt: string;
+  updatedAt: string;
+  owner: string | null;
+  files: GistFile[];
+};
+
+type GistCreateResult = {
+  created: true;
+  id: string;
+  url: string;
+  public: boolean;
+  files: string[];
+};
+
+type GistEditResult = {
+  edited: true;
+  id: string;
+  changes: string[];
+};
+
+type GistDeleteResult = {
+  deleted: boolean;
+  id: string;
+  dryRun?: true;
+  message?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const inputError = (message: string, command: string) =>
+  new GitHubCommandError({
+    message,
+    command,
+    exitCode: 1,
+    stderr: message,
+  });
+
+const parsePaths = (value: string, command: string) => {
+  const paths = value.split(",").map((path) => path.trim());
+
+  if (paths.length === 0 || paths.some((path) => path.length === 0)) {
+    return Effect.fail(
+      inputError(`--files must be comma-separated paths without empty segments: ${value}`, command),
+    );
+  }
+
+  const sensitivePath = paths.find((path) => validateFilePath(path, command) !== null);
+  if (sensitivePath !== undefined) {
+    const validation = validateFilePath(sensitivePath, command);
+    if (validation !== null) return Effect.fail(validation);
+  }
+
+  return Effect.succeed(paths);
+};
+
+const validateFilePath = (path: string, command: string) =>
+  isSensitivePath(path) ? inputError(`Refusing to read sensitive file: ${path}`, command) : null;
+
+// `gh gist create/edit` read content from files only; inline --body is staged in a temp file
+// whose basename becomes the gist filename.
+const stageBody = Effect.fn("gist.stageBody")(function* (opts: {
+  body: string;
+  filename: string;
+  command: string;
+}) {
+  const directory = yield* Effect.acquireRelease(
+    Effect.tryPromise({
+      try: async () => {
+        const proc = Bun.spawn(
+          ["mktemp", "-d", join(process.env.TMPDIR ?? "/tmp", "gh-tool-gist-XXXXXX")],
+          { stdout: "pipe", stderr: "pipe" },
+        );
+        const [exitCode, stdout, stderr] = await Promise.all([
+          proc.exited,
+          new Response(proc.stdout).text(),
+          new Response(proc.stderr).text(),
+        ]);
+
+        if (exitCode !== 0) {
+          throw new Error(stderr.trim() || `mktemp exited with code ${exitCode}`);
+        }
+
+        return stdout.trim();
+      },
+      catch: (error) =>
+        inputError(
+          `Failed to stage gist content: ${error instanceof Error ? error.message : String(error)}`,
+          opts.command,
+        ),
+    }),
+    (tempDirectory) =>
+      Effect.tryPromise({
+        try: async () => {
+          const proc = Bun.spawn(["rm", "-rf", tempDirectory], {
+            stdout: "ignore",
+            stderr: "ignore",
+          });
+          await proc.exited;
+        },
+        catch: () => undefined,
+      }).pipe(Effect.ignore),
+  );
+  const path = join(directory, opts.filename);
+
+  yield* Effect.tryPromise({
+    try: () => Bun.write(path, opts.body),
+    catch: (error) =>
+      inputError(
+        `Failed to stage gist content: ${error instanceof Error ? error.message : String(error)}`,
+        opts.command,
+      ),
+  });
+
+  return path;
+});
+
+const toListItem = (gist: GistApi): GistListItem => ({
+  id: gist.id,
+  description: gist.description,
+  public: gist.public,
+  url: gist.html_url,
+  createdAt: gist.created_at,
+  updatedAt: gist.updated_at,
+  files: Object.keys(gist.files ?? {}),
+});
+
+export const toGistDetail = (
+  gist: GistApi,
+  opts: { filename: string | null; withContent: boolean },
+): GistDetail => {
+  const files = Object.values(gist.files ?? {})
+    .filter((file) => opts.filename === null || file.filename === opts.filename)
+    .map((file) => {
+      const result: GistFile = {
+        filename: file.filename,
+        language: file.language,
+        size: file.size,
+        truncated: file.truncated ?? false,
+      };
+
+      if (opts.withContent) {
+        result.content = file.content ?? "";
+      }
+
+      return result;
+    });
+
+  return {
+    id: gist.id,
+    description: gist.description,
+    public: gist.public,
+    url: gist.html_url,
+    createdAt: gist.created_at,
+    updatedAt: gist.updated_at,
+    owner: gist.owner?.login ?? null,
+    files,
+  };
+};
+
+export const validateBodyFilename = (
+  body: string | null,
+  filename: string | null,
+  command: string,
+): GitHubCommandError | null => {
+  if (body === null) return null;
+  if (filename === null) {
+    return inputError("--filename is required with --body/--body-file", command);
+  }
+  if (filename.length === 0 || filename === "." || filename === ".." || /[\\/]/.test(filename)) {
+    return inputError("--filename must be a file name without path separators", command);
+  }
+  return null;
+};
+
+export const validateEditInput = (opts: {
+  body: string | null;
+  filename: string | null;
+  description: string | null;
+  add: string | null;
+  remove: string | null;
+}): GitHubCommandError | null => {
+  const command = "gh-tool gist edit";
+
+  if (
+    opts.body === null &&
+    opts.description === null &&
+    opts.add === null &&
+    opts.remove === null
+  ) {
+    return inputError(
+      "Provide at least one of --body/--body-file (with --filename), --desc, --add, or --remove",
+      command,
+    );
+  }
+
+  return validateBodyFilename(opts.body, opts.filename, command);
+};
+
+// ---------------------------------------------------------------------------
+// Internal handlers
+// ---------------------------------------------------------------------------
+
+const listGists = Effect.fn("gist.listGists")(function* (opts: {
+  limit: number;
+  visibility: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  const gists = yield* gh.runGhJson<GistApi[]>(["api", `gists?per_page=${opts.limit}`]);
+
+  return gists
+    .filter(
+      (gist) =>
+        opts.visibility === null || (opts.visibility === "public" ? gist.public : !gist.public),
+    )
+    .map(toListItem);
+});
+
+const viewGist = Effect.fn("gist.viewGist")(function* (opts: {
+  id: string;
+  filename: string | null;
+  withContent: boolean;
+}) {
+  const gh = yield* GitHubService;
+
+  const gist = yield* gh.runGhJson<GistApi>(["api", `gists/${opts.id}`]);
+
+  return toGistDetail(gist, { filename: opts.filename, withContent: opts.withContent });
+});
+
+export const createGist = Effect.fn("gist.createGist")(function* (opts: {
+  paths: string[];
+  description: string | null;
+  public: boolean;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = ["gist", "create", ...opts.paths];
+
+  if (opts.description !== null) {
+    args.push("--desc", opts.description);
+  }
+
+  if (opts.public) {
+    args.push("--public");
+  }
+
+  const result = yield* gh.runGh(args);
+  const url =
+    result.stdout
+      .trim()
+      .split("\n")
+      .map((line) => line.trim())
+      .findLast((line) => line.startsWith("https://")) ?? "";
+
+  if (url === "") {
+    return yield* Effect.fail(
+      inputError("gh gist create did not return a gist URL", "gh-tool gist create"),
+    );
+  }
+
+  const created: GistCreateResult = {
+    created: true,
+    id: url.split("/").at(-1) ?? "",
+    url,
+    public: opts.public,
+    files: opts.paths.map((path) => path.split("/").at(-1) ?? path),
+  };
+
+  return created;
+});
+
+const editGist = Effect.fn("gist.editGist")(function* (opts: {
+  id: string;
+  description: string | null;
+  add: string | null;
+  remove: string | null;
+  filename: string | null;
+  sourcePath: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = ["gist", "edit", opts.id];
+  const changes: string[] = [];
+
+  if (opts.sourcePath !== null) {
+    args.push(opts.sourcePath);
+    changes.push(`content:${opts.filename ?? opts.sourcePath.split("/").at(-1)}`);
+  }
+
+  if (opts.description !== null) {
+    args.push("--desc", opts.description);
+    changes.push("description");
+  }
+
+  if (opts.add !== null) {
+    args.push("--add", opts.add);
+    changes.push(`add:${opts.add.split("/").at(-1)}`);
+  }
+
+  if (opts.remove !== null) {
+    args.push("--remove", opts.remove);
+    changes.push(`remove:${opts.remove}`);
+  }
+
+  if (opts.filename !== null) {
+    args.push("--filename", opts.filename);
+  }
+
+  yield* gh.runGh(args);
+
+  const edited: GistEditResult = { edited: true, id: opts.id, changes };
+
+  return edited;
+});
+
+const deleteGist = Effect.fn("gist.deleteGist")(function* (opts: { id: string; confirm: boolean }) {
+  const gh = yield* GitHubService;
+
+  if (!opts.confirm) {
+    const dryRun: GistDeleteResult = {
+      deleted: false,
+      id: opts.id,
+      dryRun: true,
+      message: `Would delete gist ${opts.id}. Re-run with --confirm to execute.`,
+    };
+
+    return dryRun;
+  }
+
+  yield* gh.runGh(["gist", "delete", opts.id, "--yes"]);
+
+  const deleted: GistDeleteResult = { deleted: true, id: opts.id };
+
+  return deleted;
+});
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+export const gistListCommand = Command.make(
+  "list",
+  {
+    format: formatOption,
+    limit: Flag.integer("limit").pipe(
+      Flag.withDescription("Maximum number of gists to return"),
+      Flag.withDefault(10),
+    ),
+    visibility: Flag.choice("visibility", ["public", "secret"]).pipe(
+      Flag.withDescription("Filter by visibility: public or secret"),
+      Flag.optional,
+    ),
+  },
+  ({ format, limit, visibility }) =>
+    Effect.gen(function* () {
+      const requested = Option.getOrNull(visibility);
+
+      const gists = yield* listGists({ limit, visibility: requested });
+
+      yield* logFormatted(gists, format);
+    }),
+).pipe(Command.withDescription("List your gists (id, description, visibility, file names)"));
+
+export const gistViewCommand = Command.make(
+  "view",
+  {
+    filename: Flag.string("filename").pipe(
+      Flag.withDescription("Return only this file from the gist"),
+      Flag.optional,
+    ),
+    format: formatOption,
+    id: Flag.string("id").pipe(Flag.withDescription("Gist id or URL")),
+    metadataOnly: Flag.boolean("metadata-only").pipe(
+      Flag.withDescription("Omit file contents"),
+      Flag.withDefault(false),
+    ),
+  },
+  ({ filename, format, id, metadataOnly }) =>
+    Effect.gen(function* () {
+      const gist = yield* viewGist({
+        id: id.split("/").at(-1) ?? id,
+        filename: Option.getOrNull(filename),
+        withContent: !metadataOnly,
+      });
+
+      yield* logFormatted(gist, format);
+    }),
+).pipe(Command.withDescription("View a gist with file contents"));
+
+export const gistCreateCommand = Command.make(
+  "create",
+  {
+    body: Flag.string("body").pipe(
+      Flag.withDescription("Inline gist content (requires --filename)"),
+      Flag.optional,
+    ),
+    bodyFile: Flag.string("body-file").pipe(
+      Flag.withDescription(
+        "Read gist content from a file path or '-' for stdin (requires --filename)",
+      ),
+      Flag.optional,
+    ),
+    desc: Flag.string("desc").pipe(Flag.withDescription("Gist description"), Flag.optional),
+    filename: Flag.string("filename").pipe(
+      Flag.withDescription("File name used for --body/--body-file content"),
+      Flag.optional,
+    ),
+    files: Flag.string("files").pipe(
+      Flag.withDescription("Comma-separated paths of existing files to upload"),
+      Flag.optional,
+    ),
+    format: formatOption,
+    public: Flag.boolean("public").pipe(
+      Flag.withDescription("Publish as a public gist (gists are secret by default)"),
+      Flag.withDefault(false),
+    ),
+  },
+  ({ body, bodyFile, desc, filename, files, format, public: isPublic }) =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const command = "gh-tool gist create";
+        const filesValue = Option.getOrNull(files);
+        const resolvedBody = yield* resolveOptionalTextInput({
+          command,
+          value: Option.getOrNull(body),
+          fileValue: Option.getOrNull(bodyFile),
+          valueFlag: "--body",
+          fileFlag: "--body-file",
+          label: "body",
+        });
+
+        if (filesValue === null && resolvedBody === null) {
+          return yield* Effect.fail(
+            inputError("Provide --files, or --body/--body-file with --filename", command),
+          );
+        }
+
+        const paths: string[] = [];
+
+        if (filesValue !== null) {
+          paths.push(...(yield* parsePaths(filesValue, command)));
+        }
+
+        if (resolvedBody !== null) {
+          const name = Option.getOrNull(filename);
+          const filenameValidation = validateBodyFilename(resolvedBody, name, command);
+
+          if (filenameValidation !== null) {
+            return yield* Effect.fail(filenameValidation);
+          }
+
+          paths.push(yield* stageBody({ body: resolvedBody, filename: name ?? "", command }));
+        }
+
+        const created = yield* createGist({
+          paths,
+          description: Option.getOrNull(desc),
+          public: isPublic,
+        });
+
+        yield* logFormatted(created, format);
+      }),
+    ),
+).pipe(Command.withDescription("Create a gist from files or inline content (secret by default)"));
+
+export const gistEditCommand = Command.make(
+  "edit",
+  {
+    add: Flag.string("add").pipe(
+      Flag.withDescription("Path of a new file to add to the gist"),
+      Flag.optional,
+    ),
+    body: Flag.string("body").pipe(
+      Flag.withDescription("Replacement content for --filename"),
+      Flag.optional,
+    ),
+    bodyFile: Flag.string("body-file").pipe(
+      Flag.withDescription("Read replacement content from a file path or '-' for stdin"),
+      Flag.optional,
+    ),
+    desc: Flag.string("desc").pipe(Flag.withDescription("New gist description"), Flag.optional),
+    filename: Flag.string("filename").pipe(
+      Flag.withDescription("Gist file to replace with --body/--body-file"),
+      Flag.optional,
+    ),
+    format: formatOption,
+    id: Flag.string("id").pipe(Flag.withDescription("Gist id or URL")),
+    remove: Flag.string("remove").pipe(
+      Flag.withDescription("File name to remove from the gist"),
+      Flag.optional,
+    ),
+  },
+  ({ add, body, bodyFile, desc, filename, format, id, remove }) =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const command = "gh-tool gist edit";
+        const resolvedBody = yield* resolveOptionalTextInput({
+          command,
+          value: Option.getOrNull(body),
+          fileValue: Option.getOrNull(bodyFile),
+          valueFlag: "--body",
+          fileFlag: "--body-file",
+          label: "body",
+        });
+
+        const description = Option.getOrNull(desc);
+        const addPath = Option.getOrNull(add);
+        const removeName = Option.getOrNull(remove);
+        const name = Option.getOrNull(filename);
+
+        const validation = validateEditInput({
+          body: resolvedBody,
+          filename: name,
+          description,
+          add: addPath,
+          remove: removeName,
+        });
+
+        if (validation !== null) {
+          return yield* Effect.fail(validation);
+        }
+
+        if (addPath !== null) {
+          const pathValidation = validateFilePath(addPath, command);
+          if (pathValidation !== null) {
+            return yield* Effect.fail(pathValidation);
+          }
+        }
+
+        const sourcePath =
+          resolvedBody === null || name === null
+            ? null
+            : yield* stageBody({ body: resolvedBody, filename: name, command });
+
+        const edited = yield* editGist({
+          id: id.split("/").at(-1) ?? id,
+          description,
+          add: addPath,
+          remove: removeName,
+          filename: name,
+          sourcePath,
+        });
+
+        yield* logFormatted(edited, format);
+      }),
+    ),
+).pipe(Command.withDescription("Edit a gist (never opens an editor — content flags required)"));
+
+export const gistDeleteCommand = Command.make(
+  "delete",
+  {
+    confirm: Flag.boolean("confirm").pipe(
+      Flag.withDescription("Actually delete the gist (without this flag, only shows dry-run)"),
+      Flag.withDefault(false),
+    ),
+    format: formatOption,
+    id: Flag.string("id").pipe(Flag.withDescription("Gist id or URL")),
+  },
+  ({ confirm, format, id }) =>
+    Effect.gen(function* () {
+      const result = yield* deleteGist({ id: id.split("/").at(-1) ?? id, confirm });
+
+      yield* logFormatted(result, format);
+    }),
+).pipe(Command.withDescription("Delete a gist (dry-run by default, use --confirm to execute)"));

package/src/gh-tool/index.ts

@@ -51,6 +51,13 @@ import {
   prWatchCommand,
 } from "./pr/index";
 import { branchRenameCommand } from "./branch";
+import {
+  gistCreateCommand,
+  gistDeleteCommand,
+  gistEditCommand,
+  gistListCommand,
+  gistViewCommand,
+} from "./gist";
 import {
   releaseCreateCommand,
   releaseDeleteCommand,
@@ -168,6 +175,17 @@ const releaseCommand = Command.make("release", {}).pipe(
   ]),
 );
 
+const gistCommand = Command.make("gist", {}).pipe(
+  Command.withDescription("Gist operations (list, view, create, edit, delete)"),
+  Command.withSubcommands([
+    gistListCommand,
+    gistViewCommand,
+    gistCreateCommand,
+    gistEditCommand,
+    gistDeleteCommand,
+  ]),
+);
+
 const commandsCommand = makeSchemaCommand(() => mainCommand);
 
 const mainCommand = Command.make("gh-tool", {}).pipe(
@@ -200,7 +218,8 @@ WORKFLOW FOR AI AGENTS:
   20. Use 'release status' to inspect latest release + repository context
   21. Use 'release create --tag vX.Y.Z --generate-notes' to publish a release
   22. Use 'release edit/view/list/delete' to maintain existing releases
-  23. Use 'branch rename --old-name X --new-name Y --confirm' to rename a branch`,
+  23. Use 'branch rename --old-name X --new-name Y --confirm' to rename a branch
+  24. Use 'gist list/view' to read gists and 'gist create --files a.ts --desc "..."' to share snippets`,
   ),
   Command.withSubcommands([
     prCommand,
@@ -209,6 +228,7 @@ WORKFLOW FOR AI AGENTS:
     branchCommand,
     workflowCommand,
     releaseCommand,
+    gistCommand,
     commandsCommand,
   ]),
 );

package/src/gh-tool/text-input.ts

@@ -3,13 +3,21 @@ import { Effect, Schema } from "effect";
 import { GitHubCommandError } from "#gh/errors";
 
 const STDIN_SENTINEL = "-";
-const SENSITIVE_PATH_PATTERNS = [/\.env(\..+)?$/, /\.envrc$/, /\.(pem|key|p12|pfx|cer|crt)$/i];
+const SENSITIVE_PATH_PATTERNS = [
+  /\.env(\..+)?$/,
+  /\.envrc$/,
+  /\.(pem|key|p12|pfx|cer|crt)$/i,
+  /(?:^|[\\/])(credentials?|passwd|shadow)$/i,
+];
 const MissingMode = Schema.Literals(["error", "null", "default"]);
 
 const readTextFromStdin = () => Bun.stdin.text();
 
+export const isSensitivePath = (filePath: string) =>
+  SENSITIVE_PATH_PATTERNS.some((pattern) => pattern.test(filePath));
+
 const readTextFile = (filePath: string) => {
-  if (SENSITIVE_PATH_PATTERNS.some((pattern) => pattern.test(filePath))) {
+  if (isSensitivePath(filePath)) {
     return Promise.reject(new Error(`Refusing to read sensitive file: ${filePath}`));
   }