alokrajiv/astrolark

1. What this repo is

Astrolark is a TypeScript Node.js CLI for turning a project directory into an AI-friendly snapshot. Its main job is to walk a codebase, collect structure and file contents, and emit a consolidated overview in a format that can be pasted into an LLM or saved to disk.

2. Top-level command boundary

The entrypoint in src/index.ts likely wires up the CLI commands and dispatches into the two main user flows: read for generating an overview and edit for the editor pipeline. This is the primary boundary between user input and the internal processing code.

3. Interactive vs non-interactive configuration

src/wizard.ts implements the interactive setup path described in the README. The CLI can also run headless with flags like --base-path, --filter, --output, and --no-wizard, so configuration is split between a prompt-driven mode and direct argument parsing.

4. Project scanning and file selection

src/fileUtils.ts is the file-system boundary for discovering candidates, respecting .gitignore, excluding binary files, and applying include filters. This subsystem determines the exact scope of the snapshot before any formatting happens.

5. Overview generation pipeline

src/overviewGenerator.ts is the core “read” engine. It takes the selected files and project structure and produces the final overview content. This is the central transformation step from repository state to serialized summary.

6. Output formatting and delivery

The generator supports at least YAML and XML output formats, so there is a serialization layer that sits after scanning. The README also calls out clipboard copying and saving to a file, which means the final output has two sinks: local filesystem and clipboard integration.

7. Shared domain constants

src/constants.ts likely holds format names, defaults, and command-level constants used across the CLI and generator. This keeps user-facing options and internal defaults consistent across the command flow.

8. Separate editor subsystem

The src/editor directory is a distinct subsystem from the overview generator. It has its own entry module, parser, and multi-phase processor, indicating a staged transformation pipeline for a custom editor-oriented input format rather than the project scanning flow.

9. Parser and staged processing

src/editor/parser.ts converts editor input into an intermediate representation. The src/editor/processor package then runs that representation through four phases (phase1.ts through phase4.ts), with shared types in types.ts. This strongly suggests incremental normalization/validation/transformation rather than a single-pass edit operation.

10. Testing strategy and fixtures

The repository uses Jest (jest.config.mjs) and has targeted tests for the parser and the first three processor phases. The tests/editor/scenes/heartbleed fixture set, including .alk, source, and staged JSON files, shows the editor pipeline is validated with realistic multi-stage scenarios.

11. Architectural split

At a high level, the repo is divided into two domains:

- Snapshot generation: scan a project and serialize its contents for AI consumption.

- Editor processing: parse a custom editor input and evolve it through staged processing.

These domains share the same CLI/runtime but appear to be intentionally separated in the source tree.

12. Runtime and tooling

The project is a Node.js + TypeScript codebase with a lockfile and Jest-based tests. There’s no sign of a server, database, or external API dependency; the key integrations are local filesystem access, Git ignore rules, and clipboard/output handling.