docs

Author: litecreator

.gitignore

@@ -1 +1,20 @@
-target/
+# Build artifacts
+/target/
+
+# Coverage and profiling
+/coverage/
+*.profraw
+*.profdata
+
+# Logs and temp files
+*.log
+*.tmp
+*.temp
+
+# Editor and OS files
+/.idea/
+/.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db

docs/README.md

@@ -0,0 +1,21 @@
+# dustpkg Documentation
+
+This directory contains complete Markdown documentation for `dustpkg`.
+
+## Documentation Index
+
+- `getting_started.md`: installation, build, and first package workflow.
+- `architecture.md`: workspace, crate, and execution flow.
+- `cli_reference.md`: command-line contract and command behavior.
+- `manifest_reference.md`: `Dust.toml` schema and field semantics.
+- `lockfile_reference.md`: `dustpkg.lock` schema and deterministic ordering model.
+- `resolver_and_reproducibility.md`: resolver algorithm and reproducibility guarantees.
+- `library_api.md`: public Rust API surface in `crates/dustpkg/src/lib.rs`.
+- `error_handling.md`: common failures, messages, and operational guidance.
+- `testing_and_ci.md`: test coverage and CI workflow.
+
+## Scope
+
+`dustpkg` is a deterministic package manager prototype for Dust projects. It initializes package manifests, manages direct dependencies, generates lock files with checksums, and validates manifest-lock consistency during build.
+
+Current behavior focuses on deterministic dependency resolution and lockfile generation. It does not yet fetch remote registries or compile package artifacts.

docs/architecture.md

@@ -0,0 +1,51 @@
+# Architecture
+
+## Workspace Layout
+
+- `Cargo.toml`: workspace root for `crates/dustpkg`.
+- `crates/dustpkg/src/main.rs`: CLI argument parsing and command dispatch.
+- `crates/dustpkg/src/lib.rs`: manifest model, lockfile model, resolver, and package operations.
+- `crates/dustpkg/tests/cli.rs`: integration tests for user-facing CLI behavior.
+
+## Component Roles
+
+## CLI Layer (`main.rs`)
+
+- Parses subcommands: `init`, `add`, `update`, `build`.
+- Resolves current directory and `Dust.toml` path.
+- Enforces that `Dust.toml` exists for non-`init` commands.
+- Delegates all package logic to library functions.
+
+## Library Layer (`lib.rs`)
+
+- Defines data models:
+  - `PackageInfo`
+  - `Manifest`
+  - `LockedDep`
+  - `Lockfile`
+- Implements I/O:
+  - `Manifest::load/save`
+  - `Lockfile::load/save`
+- Implements operations:
+  - `init_package`
+  - `add_dependency`
+  - `add_stdlib_dependencies`
+  - `update_lock`
+  - `build_package`
+- Implements deterministic resolver:
+  - `resolve(manifest, seed)`
+
+## Data Flow
+
+1. Command enters CLI (`main.rs`).
+2. CLI validates preconditions (for example `Dust.toml` presence).
+3. Library reads/updates manifest.
+4. Library resolves dependencies into lock entries.
+5. Lockfile is written to `dustpkg.lock`.
+6. `build` verifies manifest dependency set matches lock versions.
+
+## Determinism Model
+
+- With `seed = None`: dependencies are sorted alphabetically.
+- With `seed = Some(n)`: dependencies are shuffled using `ChaCha8Rng` seeded with `n`.
+- Checksums are deterministic SHA-256 over `"name@version"`.

docs/cli_reference.md

@@ -0,0 +1,96 @@
+# CLI Reference
+
+## Binary
+
+`dustpkg`
+
+## Global Form
+
+```text
+dustpkg <COMMAND> [OPTIONS]
+```
+
+## Commands
+
+## `init`
+
+Initialize a new package in the current directory.
+
+```text
+dustpkg init
+```
+
+Behavior:
+
+- Creates `Dust.toml` with default package metadata.
+- Fails if `Dust.toml` already exists.
+
+## `add`
+
+Add one dependency to manifest and regenerate lockfile.
+
+```text
+dustpkg add <name> <version> [--seed <u64>]
+```
+
+Arguments:
+
+- `name`: dependency key.
+- `version`: dependency version string.
+
+Options:
+
+- `--seed <u64>`: deterministic seed for dependency ordering.
+
+Behavior:
+
+- Requires `Dust.toml` to already exist.
+- Updates `[dependencies]` in manifest.
+- Rewrites `dustpkg.lock` using `resolve`.
+
+## `update`
+
+Regenerate lockfile from current manifest.
+
+```text
+dustpkg update [--seed <u64>]
+```
+
+Options:
+
+- `--seed <u64>`: deterministic seed for dependency ordering.
+
+Behavior:
+
+- Requires `Dust.toml`.
+- Does not change manifest.
+- Rewrites `dustpkg.lock`.
+
+## `build`
+
+Validate manifest and lockfile consistency.
+
+```text
+dustpkg build [--seed <u64>]
+```
+
+Options:
+
+- `--seed <u64>`: if provided, lockfile is updated first with this seed.
+
+Behavior:
+
+- Requires `Dust.toml`.
+- Calls `update_lock` before validation.
+- Ensures each manifest dependency exists in lockfile with matching version.
+- Prints success on pass.
+
+## Current Exit/Failure Conditions
+
+Representative failures:
+
+- `Dust.toml not found in <cwd>`
+- `Dust.toml already exists in <dir>`
+- Parse/read/write failures with path context
+- `dependency '<name>' missing from lock file`
+- `version mismatch for dependency '<name>'`

docs/error_handling.md

@@ -0,0 +1,50 @@
+# Error Handling
+
+## Error Model
+
+`dustpkg` uses `anyhow::Result` and attaches path/context strings for I/O and parse operations.
+
+Primary error sources:
+
+- Missing files
+- Invalid TOML format
+- Serialization/write failures
+- Manifest-lock validation failures
+
+## Common User-Facing Errors
+
+## Missing Manifest
+
+For `add`, `update`, and `build`:
+
+```text
+Dust.toml not found in <cwd>
+```
+
+## Manifest Already Exists
+
+For `init` in a non-empty project:
+
+```text
+Dust.toml already exists in <dir>
+```
+
+## Manifest/Lock Parse Failures
+
+Typical context wrappers:
+
+- `failed to read manifest at <path>`
+- `failed to parse manifest at <path>`
+- `failed to read lock file at <path>`
+- `failed to parse lock file at <path>`
+
+## Consistency Failures During Build
+
+- `dependency '<name>' missing from lock file`
+- `version mismatch for dependency '<name>': manifest <v1> vs lock <v2>`
+
+## Operational Guidance
+
+- Run `dustpkg update` after editing dependencies manually.
+- Re-run `build` to validate lockfile alignment.
+- Keep `Dust.toml` and `dustpkg.lock` committed together.

docs/getting_started.md

@@ -0,0 +1,84 @@
+# Getting Started
+
+## Prerequisites
+
+- Rust toolchain compatible with edition 2021.
+- `cargo` available in PATH.
+- A working directory where `dustpkg` can create `Dust.toml` and `dustpkg.lock`.
+
+## Build
+
+From `dustpkg/`:
+
+```bash
+cargo build --release
+```
+
+Run the CLI with:
+
+```bash
+cargo run -p dustpkg -- <command>
+```
+
+## First Project Workflow
+
+Create a new project directory and initialize:
+
+```bash
+mkdir hello_dust
+cd hello_dust
+cargo run -p dustpkg -- init
+```
+
+Expected result:
+
+- `Dust.toml` is created.
+- Package name defaults to the current directory name.
+- Version defaults to `0.1.0`.
+- `dpl_version` defaults to `0.2`.
+
+Add dependencies:
+
+```bash
+cargo run -p dustpkg -- add serde 1.0.0
+cargo run -p dustpkg -- add rand 0.8.5 --seed 42
+```
+
+Expected result:
+
+- `Dust.toml` dependency map is updated.
+- `dustpkg.lock` is regenerated.
+- Checksums are recorded for each dependency.
+
+Update lock file without changing manifest:
+
+```bash
+cargo run -p dustpkg -- update
+```
+
+Validate manifest-lock consistency:
+
+```bash
+cargo run -p dustpkg -- build
+```
+
+## Typical Files After Setup
+
+`Dust.toml`:
+
+```toml
+[package]
+name = "hello_dust"
+version = "0.1.0"
+dpl_version = "0.2"
+
+[dependencies]
+serde = "1.0.0"
+rand = "0.8.5"
+```
+
+`dustpkg.lock` includes:
+
+- `package` metadata copied from manifest.
+- `dependencies` array with `name`, `version`, `checksum`, and `source`.
+- Optional `seed` when provided.