@aurora.purecore.codes/latest 1.0.0

package/QUICK_START.md

@@ -0,0 +1,344 @@
+# Aurora Austral - Quick Start Guide
+
+Get started with Aurora Austral in 5 minutes! 🚀
+
+## Installation
+
+```bash
+npm install -g aurora-npm
+```
+
+## Create Your First Project
+
+```bash
+# 1. Create project directory
+mkdir hello-aurora
+cd hello-aurora
+
+# 2. Initialize project (downloads compiler automatically)
+aurora init
+
+# 3. Build and run
+make build
+./main
+```
+
+**Output:**
+```
+Hello, Aurora Austral!
+```
+
+That's it! You now have a working Aurora Austral project. 🎉
+
+## What Just Happened?
+
+The `aurora init` command:
+
+1. ✅ Downloaded the Austral compiler binary for your platform
+2. ✅ Downloaded the standard library
+3. ✅ Created project structure with example code
+4. ✅ Generated a Makefile for easy building
+5. ✅ Set up `.gitignore` for version control
+
+## Project Structure
+
+```
+hello-aurora/
+├── aurora.json          # Project configuration
+├── Makefile            # Build configuration
+├── src/
+│   ├── Main.aui        # Module interface
+│   └── Main.aum        # Module implementation
+├── .aurora/
+│   ├── bin/austral     # Compiler (downloaded)
+│   └── stdlib/         # Standard library (downloaded)
+└── aurora_packages/    # Installed packages
+```
+
+## Next Steps
+
+### 1. Edit Your Code
+
+Open `src/Main.aum` and modify it:
+
+```austral
+module body Example.Main is
+    function main(): ExitCode is
+        printLn("Welcome to Aurora Austral!");
+        printLn("A language with linear types!");
+        return ExitSuccess();
+    end;
+end module body.
+```
+
+### 2. Rebuild and Run
+
+```bash
+make build
+./main
+```
+
+### 3. Install Packages
+
+```bash
+# List available packages
+aurora list
+
+# Install a package
+aurora install dpop-token
+
+# Use it in your code
+```
+
+### 4. Use Installed Packages
+
+Edit `src/Main.aui`:
+
+```austral
+module Example.Main is
+    import DpopToken (
+        generateToken,
+        TokenConfig
+    );
+    
+    function main(): ExitCode;
+end module.
+```
+
+Edit `src/Main.aum`:
+
+```austral
+module body Example.Main is
+    function main(): ExitCode is
+        let config: TokenConfig := makeTokenConfig();
+        let token: String := generateToken(config);
+        printLn(token);
+        return ExitSuccess();
+    end;
+end module body.
+```
+
+## Common Commands
+
+```bash
+# Initialize new project
+aurora init
+
+# Install package
+aurora install <package-name>
+
+# List available packages
+aurora list
+
+# Search for packages
+aurora find <search-term>
+
+# Update packages
+aurora update
+
+# Build project
+make build
+
+# Run project
+./main
+
+# Clean build artifacts
+make clean
+```
+
+## Platform Support
+
+Aurora init automatically detects your platform and downloads the correct binary:
+
+- ✅ **Linux x64** - Native support
+- ✅ **macOS Intel** - Native support
+- ✅ **macOS Apple Silicon** - Native support (M1/M2/M3)
+- ✅ **Windows x64** - Via WSL
+
+## Without Binary Download
+
+If you prefer to install the compiler manually:
+
+```bash
+# Initialize without downloading binaries
+aurora init --no-binary
+
+# Make sure 'austral' is in your PATH
+which austral
+
+# Build normally
+make build
+```
+
+## VSCode Extension
+
+For the best development experience, install the Aurora Austral VSCode extension:
+
+1. Open VSCode
+2. Go to Extensions (Ctrl+Shift+X)
+3. Search for "Aurora Austral"
+4. Install
+
+**Features:**
+- Syntax highlighting
+- Code snippets
+- Package validation
+- One-click package installation
+- Error detection
+
+## Example Projects
+
+### Hello World
+
+```austral
+module body Example.Main is
+    function main(): ExitCode is
+        printLn("Hello, World!");
+        return ExitSuccess();
+    end;
+end module body.
+```
+
+### String Manipulation
+
+```austral
+module body Example.Main is
+    function main(): ExitCode is
+        let name: String := "Aurora";
+        let greeting: String := concat("Hello, ", name);
+        printLn(greeting);
+        return ExitSuccess();
+    end;
+end module body.
+```
+
+### Using Standard Library
+
+```austral
+module body Example.Main is
+    import Austral.String (
+        concat,
+        length
+    );
+    
+    function main(): ExitCode is
+        let text: String := "Aurora Austral";
+        let len: Nat64 := length(text);
+        printLn(concat("Length: ", intToString(len)));
+        return ExitSuccess();
+    end;
+end module body.
+```
+
+## Troubleshooting
+
+### "austral: command not found"
+
+**Solution:** Run `aurora init` again - it will download the compiler.
+
+### "Permission denied" when running ./main
+
+**Solution:**
+```bash
+chmod +x .aurora/bin/austral
+chmod +x main
+```
+
+### Build fails with "AUSTRAL_STDLIB not found"
+
+**Solution:** The stdlib wasn't downloaded. Run:
+```bash
+aurora init
+```
+
+### Package installation fails
+
+**Solution:**
+```bash
+# Clear cache and retry
+aurora uninstall <package-name>
+rm -rf ~/.aurora_austral/packages/<package-name>
+aurora install <package-name>
+```
+
+## Learning Resources
+
+- **Official Docs**: https://austral-lang.org/
+- **Tutorial**: https://austral-lang.org/tutorial/
+- **Specification**: https://austral-lang.org/spec/
+- **Examples**: Check `examples/` in the compiler repository
+
+## Key Concepts
+
+### Linear Types
+
+Aurora Austral uses linear types for memory safety:
+
+```austral
+-- Each value must be used exactly once
+let x: String := "Hello";
+consume(x);  -- x is now consumed
+-- Cannot use x again!
+```
+
+### Module System
+
+Every file has an interface (`.aui`) and implementation (`.aum`):
+
+```austral
+-- Main.aui (interface)
+module Example.Main is
+    function greet(name: String): String;
+end module.
+
+-- Main.aum (implementation)
+module body Example.Main is
+    function greet(name: String): String is
+        return concat("Hello, ", name);
+    end;
+end module body.
+```
+
+### Memory Safety
+
+No garbage collection, no manual memory management:
+
+```austral
+-- Compiler tracks ownership and lifetime
+let buffer: Buffer := makeBuffer(1024);
+writeToBuffer(buffer, "data");
+-- buffer is automatically freed when out of scope
+```
+
+## Getting Help
+
+- **GitHub Issues**: https://github.com/austral/austral/issues
+- **Discussions**: https://github.com/austral/austral/discussions
+- **Package Manager Issues**: https://github.com/Aurora-Austral/aurora-npm/issues
+
+## What's Next?
+
+1. ✅ Read the [Tutorial](https://austral-lang.org/tutorial/)
+2. ✅ Explore [Examples](https://github.com/austral/austral/tree/master/examples)
+3. ✅ Install the [VSCode Extension](vscode:extension/aurora-austral)
+4. ✅ Join the [Community](https://github.com/austral/austral/discussions)
+5. ✅ Build something awesome!
+
+## Summary
+
+```bash
+# Complete workflow in 4 commands:
+mkdir my-project && cd my-project  # 1. Create directory
+aurora init                         # 2. Initialize project
+make build                          # 3. Build
+./main                              # 4. Run
+```
+
+Welcome to Aurora Austral! 🎉
+
+---
+
+**Need more details?** Check out:
+- [README.md](README.md) - Full documentation
+- [BINARY_RELEASE.md](BINARY_RELEASE.md) - Binary compilation guide
+- [TEST_INIT_COMMAND.md](TEST_INIT_COMMAND.md) - Testing guide

package/README.md

@@ -0,0 +1,333 @@
+# Aurora Package Manager
+
+Gerenciador de pacotes para a linguagem Aurora Austral **sem dependências externas**.
+
+## Instalação
+
+```bash
+npm install -g aurora-npm
+```
+
+**Nota:** Este package não tem dependências externas. Usa apenas o Node.js nativo (fetch, fs, path, os, child_process).
+
+## Requisitos
+
+- Node.js >= 18.0.0 (para suporte nativo a `fetch`)
+- WSL (opcional, para Windows)
+
+## Comandos
+
+### `aurora init`
+
+Inicializa um novo projeto Aurora Austral com estrutura completa:
+
+```bash
+aurora init
+```
+
+O que faz:
+- ✅ Cria `aurora.json` com configuração do projeto
+- ✅ Cria estrutura de diretórios (`src/`, `aurora_packages/`, `.aurora/`)
+- ✅ **Baixa binário do compilador** para a plataforma atual
+- ✅ **Baixa biblioteca padrão**
+- ✅ Cria arquivos de exemplo (`src/Main.aui`, `src/Main.aum`)
+- ✅ Cria `Makefile` configurado
+- ✅ Cria `.gitignore`
+
+**Opções:**
+- `--no-binary`: Não baixa binários (usa instalação do sistema)
+
+**Exemplo:**
+```bash
+mkdir meu-projeto
+cd meu-projeto
+aurora init
+
+# Compilar e executar
+make build
+./main
+```
+
+### `aurora install <package>`
+
+Instala um pacote do repositório:
+
+```bash
+aurora install dpop-token
+```
+
+O que faz:
+- Baixa o pacote do GitHub
+- Compila o pacote
+- Executa testes
+- Salva em cache local
+
+### `aurora list`
+
+Lista pacotes disponíveis:
+
+```bash
+# Listar pacotes remotos
+aurora list
+
+# Listar pacotes em cache local
+aurora list --local
+```
+
+### `aurora find <nome>`
+
+Busca pacotes por nome:
+
+```bash
+aurora find dpop
+```
+
+### `aurora uninstall <package>`
+
+Remove um pacote:
+
+```bash
+aurora uninstall dpop-token
+```
+
+### `aurora update [package]`
+
+Atualiza pacotes:
+
+```bash
+# Atualizar todos os pacotes
+aurora update
+
+# Atualizar pacote específico
+aurora update dpop-token
+```
+
+### `aurora test <package>`
+
+Executa testes de um pacote:
+
+```bash
+aurora test dpop-token
+```
+
+## Estrutura de Projeto
+
+Após `aurora init`:
+
+```
+meu-projeto/
+├── aurora.json              # Configuração do projeto
+├── Makefile                 # Build configuration
+├── .gitignore              # Git ignore
+├── src/
+│   ├── Main.aui            # Interface do módulo principal
+│   └── Main.aum            # Implementação do módulo principal
+├── aurora_packages/        # Pacotes instalados
+└── .aurora/
+    ├── bin/
+    │   └── austral         # Compilador (baixado automaticamente)
+    └── stdlib/             # Biblioteca padrão (baixada automaticamente)
+```
+
+## aurora.json
+
+Arquivo de configuração do projeto:
+
+```json
+{
+  "name": "meu-projeto",
+  "version": "0.1.0",
+  "description": "Aurora Austral project",
+  "main": "src/Main.aum",
+  "scripts": {
+    "build": "make",
+    "test": "make test",
+    "clean": "make clean"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "aurora": {
+    "compiler": "local",
+    "compilerPath": ".aurora/bin/austral",
+    "stdlibPath": ".aurora/stdlib"
+  }
+}
+```
+
+## Binários Pré-compilados
+
+O comando `aurora init` baixa automaticamente binários pré-compilados para:
+
+- **Linux x64** (`linux-x64`)
+- **macOS x64** (`darwin-x64`)
+- **macOS ARM64** (`darwin-arm64` - M1/M2)
+- **Windows x64** (`win32-x64`)
+
+Os binários são baixados do GitHub Releases e salvos em:
+- Cache global: `~/.aurora_austral/bin/`
+- Projeto local: `.aurora/bin/`
+
+## Workflow Típico
+
+### 1. Criar Novo Projeto
+
+```bash
+mkdir meu-app
+cd meu-app
+aurora init
+```
+
+### 2. Desenvolver
+
+Edite `src/Main.aum`:
+
+```austral
+module body Example.Main is
+    function main(): ExitCode is
+        printLn("Hello, Aurora!");
+        printLn("A language with linear types!");
+        return ExitSuccess();
+    end;
+end module body.
+```
+
+### 3. Instalar Dependências
+
+```bash
+aurora install dpop-token
+aurora install http-client
+```
+
+### 4. Compilar e Executar
+
+```bash
+make build
+./main
+```
+
+### 5. Testar
+
+```bash
+make test
+```
+
+## Sem Binários Pré-compilados
+
+Se preferir usar uma instalação manual do compilador:
+
+```bash
+# Inicializar sem baixar binários
+aurora init --no-binary
+
+# O Makefile usará 'austral' do PATH do sistema
+make build
+```
+
+## Cache
+
+Os pacotes e binários são salvos em cache:
+
+```
+~/.aurora_austral/
+├── packages/          # Pacotes instalados
+└── bin/              # Binários do compilador
+    ├── austral       # Compilador
+    └── stdlib/       # Biblioteca padrão
+```
+
+## Desenvolvimento
+
+### Compilar Binários para Release
+
+```bash
+cd aurora-npm
+./scripts/build-release.sh 0.2.0
+```
+
+Isso cria:
+- `releases/austral-<platform>-<arch>` - Binário compilado
+- `releases/austral-<platform>-<arch>.sha256` - Checksum
+- `releases/stdlib-v0.2.0/` - Biblioteca padrão
+- `releases/release-info-v0.2.0.txt` - Informações do release
+
+### Fazer Release no GitHub
+
+```bash
+# Criar tag
+git tag -a v0.2.0 -m "Release v0.2.0"
+git push origin v0.2.0
+
+# Criar release com binários
+gh release create v0.2.0 \
+  releases/austral-linux-x64 \
+  releases/austral-darwin-x64 \
+  releases/austral-darwin-arm64 \
+  releases/austral-win32-x64.exe \
+  --title "Aurora Austral v0.2.0" \
+  --notes "Compiled binaries for multiple platforms"
+```
+
+Veja [BINARY_RELEASE.md](BINARY_RELEASE.md) para mais detalhes.
+
+## Plataformas Suportadas
+
+### Compilador
+- Linux x64
+- macOS x64 (Intel)
+- macOS ARM64 (Apple Silicon)
+- Windows x64 (via WSL)
+
+### Package Manager
+- Linux
+- macOS
+- Windows (com WSL)
+
+## Troubleshooting
+
+### Binário não executa
+
+**Linux/macOS:**
+```bash
+chmod +x .aurora/bin/austral
+./.aurora/bin/austral --version
+```
+
+**Windows:**
+- Certifique-se de que o WSL está instalado
+- O comando `make` será executado via WSL automaticamente
+
+### Erro "AUSTRAL_STDLIB not found"
+
+```bash
+# Baixar stdlib manualmente
+aurora init --no-binary
+# Ou definir variável de ambiente
+export AUSTRAL_STDLIB=/usr/local/lib/austral/standard/src
+```
+
+### Pacote não compila
+
+```bash
+# Limpar cache e reinstalar
+aurora uninstall <package>
+rm -rf ~/.aurora_austral/packages/<package>
+aurora install <package>
+```
+
+## Contribuindo
+
+1. Fork o repositório
+2. Crie uma branch: `git checkout -b feature/nova-feature`
+3. Commit: `git commit -m 'Adiciona nova feature'`
+4. Push: `git push origin feature/nova-feature`
+5. Abra um Pull Request
+
+## Licença
+
+Apache-2.0
+
+## Links
+
+- [Aurora Austral](https://github.com/austral/austral)
+- [Package Vault](https://github.com/Aurora-Austral/vault)
+- [Documentação](https://austral-lang.org/)