prehistoric-systems/itty-bitty
1
0
Fork 0
mirror of https://github.com/arfct/itty-bitty.git synced 2026-03-11 08:54:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
itty-bitty/AGENTS.md
google-labs-jules[bot] be79518f7f feat: Implement Agent-Assisted Hypermedia Encoding CLI (AAH-CLI) 
This commit introduces the AAH-CLI, a Node.js command-line tool for creating `itty.bitty`-style URL fragments.

The CLI includes two main commands:
- `encode`: Compresses text content using Gzip or LZMA and outputs a Base64-encoded string. It accepts input from files, direct text strings, or stdin.
- `publish`: Encodes content and then publishes the resulting link to a specified file within a GitHub repository. This command uses Git to clone, modify, commit, and push the changes.

The project is structured into modular components for encoding (`encoder.js`) and publishing (`publisher.js`), with a manual argument parser in the main `aah-cli.js` file for robustness.

Includes comprehensive `README.md` and `AGENTS.md` documentation.
2025-09-08 11:08:09 +00:00

2.5 KiB
Raw Blame History

AAH-CLI Agent Development Guide

This document provides guidance for AI agents modifying or extending the Agent-Assisted Hypermedia Encoding CLI (AAH-CLI).

Project Architecture

The project is structured into three main components:

  1. aah-cli.js (The Dispatcher)

    • This is the main entry point for the CLI.
    • It is responsible for parsing the top-level command (encode, publish) and dispatching control to the appropriate handler function.
    • It uses a manual, minimalist argument parsing approach. Do not introduce complex parsing libraries like yargs unless absolutely necessary, as they have proven difficult to debug in this environment.
    • Each command has a corresponding handle...Command function and a print...Help function.

  2. encoder.js (The Core Logic)

    • This module contains the pure, dependency-free logic for the core task: compressing and encoding text.
    • It exports a single function, encode(text, algorithm).
    • It uses Node.js's built-in zlib for Gzip compression and the lzma-native library for LZMA compression.
    • If you need to add a new compression algorithm, add it here.

  3. publisher.js (The Git Integration)

    • This module handles all interactions with Git and GitHub.
    • It uses the simple-git library.
    • It exports a single function, publish(options), which performs the clone, edit, commit, and push sequence in a temporary directory.

How to Extend the CLI

Adding a New Command

  1. Add the new command name to the switch statement in the main function in aah-cli.js.
  2. Create a new handleYourCommand(args) function to contain the logic for the command.
  3. Create a parseYourCommandArgs(args) function to handle parsing its specific arguments.
  4. Create a printYourCommandHelp() function to display its help text.
  5. Update the main printHelp() function to include your new command.

Modifying an Existing Command

  • Locate the appropriate handle...Command function in aah-cli.js.
  • If the change involves core encoding or publishing logic, modify the encoder.js or publisher.js modules respectively. Keep the concerns separated.

Testing

  • The publish command is difficult to test in a sandboxed environment. Use "dry runs" that test the logic up to the point of the network call (e.g., git clone or git push).
  • For other commands, create temporary files and use echo to test all input methods (--file, --text, stdin).
  • Always clean up temporary files after your tests are complete.