Imported from aadilmallick/global-scripts-manager (AGENTS.md). Install upstream with npx skills add aadilmallick/global-scripts-manager. Copyright stays with the author.

AGENTS.md

Guidance for AI agents and developers working on Global Scripts Manager (GSM) — an interactive, cross-platform CLI for managing personal scripts and making them globally callable from anywhere on your system.

Full user + developer documentation lives in DOCS/. This file is the fast, codebase-oriented orientation. When in doubt, read the code — this file is a map, not the territory.

1. Project overview

• What it does: An interactive terminal UI (main.ts) that lets a user create, delete, edit, list, copy, and open scripts, and optionally add them to $PATH so they can be run from any directory.
• Stack: Deno 2 + TypeScript. Node built-ins via node: imports. UI deps pulled from npm (ora, inquirer, @inquirer/prompts, gradient-string, figlet). Colors via jsr:@std/internal/styles. CI pins Deno v2.9.3 for Windows ARM64 compilation.
• State/persistence: No database. Script metadata is stored as JSON at ~/.global_scripts_manager/scripts.json (or $ROOT_FOLDER/scripts.json); script bodies live in ~/.global_scripts_manager/scripts/<name>-<id>/<name>.
• Target platforms: macOS, Linux, Windows (shell-profile-based PATH editing, per-OS clipboard/terminal handling).
• Deployment: GitHub Actions tests and cross-compiles Linux x86_64/ARM64, Windows x86_64/ARM64, and macOS x86_64/ARM64 binaries. It uploads immutable workflow artifacts on main pushes and PRs, publishes binaries plus checksums as GitHub Release assets on v* tag pushes, and maintains a generated Homebrew formula. install.sh provides the macOS/Linux curl installer. Docker image also provided.

2. Quick commands

Run everything from the repo root. Deno 2 is required (deno --version).

⚠️ Validation gotcha: deno run executes without strict type-checking in Deno 2, so a change can run even when it wouldn't pass deno check. Run deno check to be sure.

3. Project structure

main.ts            Entry point + ALL action handlers (create/delete/edit/list/copy/open/quit flows)
main_test.ts       Tests (currently one test: getTextChunks)
globals.ts         Path config: root folder, scripts dir, JSON dir (env-overridable)
deno.json          Task definitions + import map
api/
  CLI.ts           Platform detection, shell detection, clipboard, subprocess helpers, open-in-terminal
  FileManager.ts   Filesystem helpers + PATH profile editing (addToPath/removeFromPath) + script scaffolding
  ScriptModel.ts   Script type, ScriptsModel (reactive), PathsHandler, ScriptsJSONHandler (persistence)
  patterns.ts      Reactive primitives: createSignal/createEffect/createMemo, StateManager, proxy helper
  tags.ts          Tag parsing/collection helpers
  cliUtilities.ts  Prompt/spinner/streaming UI helpers (inquirer, ora, figlet)
.github/workflows/
  create_executable.yaml   CI: test, cross-compile, upload artifacts, publish releases, update formula
scripts/
  generate_homebrew_formula.sh  Release checksum + Homebrew formula generator
install.sh              macOS/Linux curl installer
Dockerfile / docker-compose.yml   Containerized runs (IN_DOCKER=true)

4. How the app works (data flow)

1. main.ts bootstraps: PathsHandler → ScriptsJSONHandler → loadScriptsFromFile() → ScriptsModel.
2. chooseAction() shows the main menu (showQuickPick via inquirer) and dispatches to a handler.
3. Every mutation goes through ScriptsModel (in-memory, signal-backed) and is persisted by jsonHandler.writeScriptsToFile(scriptModel.scripts).
4. "Global" scripts get their containing folder appended to the user's shell profile (~/.zshrc, ~/.bashrc, ~/.profile, or PowerShell $PROFILE) — the user must source or restart their shell.
5. IN_DOCKER=true bypasses the character-by-character text streaming (uses plain console.log).

File identity rule (important): a script's filepath is derived from its name + id: <root>/scripts/<name>-<id>/<name>. The id (crypto.randomUUID()) makes names unique on disk even if a user reuses a display name. The folder is what gets added to $PATH.

5. Conventions & patterns to follow

• Reactive state: ScriptsModel uses createSignal/createEffect from api/patterns.ts (SolidJS-style). The #scripts private field is mirrored into a signal; every setter notifies effects. Use scriptModel.editScript(...) rather than mutating arrays directly.
• Persistence discipline: any change to scripts/tags must end in jsonHandler.writeScriptsToFile(scriptModel.scripts) (and jsonHandler.addTags(...) for new tags). The global tags set in ScriptsJSONHandler is the source of truth for the tag registry in scripts.json metadata.
• UI helpers: prefer api/cliUtilities.ts (showQuickPick, getConfirm, getInput, showLoader). Note that main.ts inconsistently uses Deno's raw prompt() for the script-name and tag prompts — prefer the helpers for new code.
• FS access: use FileManager static methods (they throw descriptive errors and guard existence). Don't call node:fs directly in new code without reason.
• Platform branching: use CLI.isLinux()/isWindows()/isMacOS() and CLI.getShell(); never hardcode a shell or clipboard command.
• Colors: import from jsr:@std/internal@^1.0.5/styles (e.g. green, red, bgGreen) as done in main.ts.
• New top-level action? Add the option string to the actions array in chooseAction(), write a handler, and add a case in the switch. Keep handlers in main.ts (current convention).
• Tests: keep using @std/assert (deno.test blocks). Remember tests must be run with -A.

6. Environment variables

7. Known issues & pitfalls (verified)

1. Type errors in copyToClipboard (fixed). api/CLI.ts previously passed stdio: ["piped", "ignore", "pipe"] — the invalid IOType "piped" (should be "pipe") collapsed child to type never, causing 9 TS errors under deno check/deno compile and blocking the CI compile workflow. Fixed: "piped" → "pipe".
2. Duplicate-name check (fixed). createScript() previously called isScriptNameUnique(finalScriptName) — the previous (initially empty) name — so duplicate display names were allowed. Fixed: it now checks isScriptNameUnique(scriptName), the name the user just entered.
3. Tests must run with -A. deno test main_test.ts fails with NotCapable: Requires env access to "TF_BUILD" (chalk does env probing).
4. First-run ordering dependency. ScriptsJSONHandler.upsertFolder() calls fs.stat with no try/catch, so a write fails if the root folder is missing. In practice main.ts creates the script folder first (which recursively creates the root), so first-run works — keep that ordering if you refactor.
5. Renaming only renames the file. editScript → edit name renames <folder>/<name> to <folder>/<newName> but leaves the folder named <oldName>-<id>. For global scripts the folder is what's on $PATH, so the new name may not be invocable until the folder is renamed too.
6. Release architecture scope. The workflow publishes Linux x86_64/ARM64, Windows x86_64/ARM64, and macOS x86_64/ARM64.
7. deno fmt --check and deno lint fail. 17 of 22 files are not deno fmt-formatted, and deno lint reports 34 problems (18 no-unused-vars, 6 no-import-prefix, 5 no-unversioned-import, 3 no-explicit-any, 2 require-await). Don't reformat the whole repo without asking — but do keep new code formatted and lint-clean.
8. Minor: unused imports (bgRed, yellow) in main.ts; getAddRunScriptInfo(), onScriptsChange(), StateManager/createMemo/withImmutable are currently unused by the main flow; isPinned/schedule fields exist in the model but are not surfaced in the UI.

See DOCS/development.md for the full list.

8. Do / Don't

• Do keep the reactive model + explicit writeScriptsToFile pattern.
• Do preserve cross-platform behavior (PATH profiles, clipboard, terminal opening).
• Do run deno test -A main_test.ts and deno check ... before finishing — both should pass cleanly now.
• Don't change storage layout (scripts/<name>-<id>/<name>, scripts.json schema) without updating ScriptModel.ts, globals.ts, and .gitignore.
• Don't add new npm/jsr deps casually — verify with deno add/lockfile updates and keep the dependency set small.