docs: update scripts docs

* Add an aside for symlink errors on Windows

* Remove redundant whitespace

* Inline URL

Co-authored-by: dai <72147841+daimond113@users.noreply.github.com>

* Revert titles to "Caution" instead of "Warning"

* Use inline code block for error message

* Update docs/src/content/docs/installation.mdx

Co-authored-by: dai <72147841+daimond113@users.noreply.github.com>

* Update docs/src/content/docs/installation.mdx

Co-authored-by: dai <72147841+daimond113@users.noreply.github.com>

---------

Co-authored-by: dai <72147841+daimond113@users.noreply.github.com>

.github/workflows/debug.yml

@@ -0,0 +1,79 @@
+name: Debug
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  get-version:
+    name: Get build version
+    runs-on: ubuntu-latest
+    outputs:
+      version: v${{ steps.get_version.outputs.value }}+rev.g${{ steps.trim_sha.outputs.trimmed_sha }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+    
+      - name: Get package version
+        uses: SebRollen/toml-action@v1.2.0
+        id: get_version
+        with:
+          file: Cargo.toml
+          field: package.version
+
+      - name: Trim commit SHA
+        id: trim_sha
+        run: |
+          commit_sha=${{ github.sha }}
+          echo "trimmed_sha=${commit_sha:0:7}" | tee $GITHUB_OUTPUT
+  build:
+    strategy:
+      matrix:
+        include:
+          - job-name: windows-x86_64
+            target: x86_64-pc-windows-msvc
+            runs-on: windows-latest
+            artifact-name: pesde-debug-${{ needs.get-version.outputs.version }}-windows-x86_64
+
+          - job-name: linux-x86_64
+            target: x86_64-unknown-linux-gnu
+            runs-on: ubuntu-latest
+            artifact-name: pesde-debug-${{ needs.get-version.outputs.version }}-linux-x86_64
+
+          - job-name: macos-x86_64
+            target: x86_64-apple-darwin
+            runs-on: macos-13
+            artifact-name: pesde-debug-${{ needs.get-version.outputs.version }}-macos-x86_64
+
+          - job-name: macos-aarch64
+            target: aarch64-apple-darwin
+            runs-on: macos-latest
+            artifact-name: pesde-debug-${{ needs.get-version.outputs.version }}-macos-aarch64
+
+    name: Build for ${{ matrix.job-name }}
+    runs-on: ${{ matrix.runs-on }}
+    needs: get-version
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Install Linux build dependencies
+      if: ${{ matrix.runs-on == 'ubuntu-latest' }}
+      run: |
+        sudo apt-get update
+        sudo apt-get install libdbus-1-dev pkg-config
+
+    - name: Install Rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+
+    - name: Compile in debug mode
+      run: cargo build --bins --no-default-features --features bin,patches,wally-compat --target ${{ matrix.target }} --locked
+
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ matrix.artifact-name }}
+        if-no-files-found: error
+        path: |
+          target/${{ matrix.target }}/debug/pesde.exe
+          target/${{ matrix.target }}/debug/pesde

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.3] - 2024-12-30
+### Added
+- Add meta field in index files to preserve compatibility with potential future changes by @daimond113
+
+### Changed
+- Remove verbosity from release mode logging by @daimond113
+
 ## [0.5.2] - 2024-12-19
 ### Fixed
 - Change dependency types for removed peer dependencies by @daimond113
@@ -105,6 +112,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Asyncify dependency linking by @daimond113
 - Use `exec` in Unix bin linking to reduce the number of processes by @daimond113
 
+[0.5.3]: https://github.com/daimond113/pesde/compare/v0.5.2%2Bregistry.0.1.1..v0.5.3%2Bregistry.0.1.2
 [0.5.2]: https://github.com/daimond113/pesde/compare/v0.5.1%2Bregistry.0.1.0..v0.5.2%2Bregistry.0.1.1
 [0.5.1]: https://github.com/daimond113/pesde/compare/v0.5.0%2Bregistry.0.1.0..v0.5.1%2Bregistry.0.1.0
 [0.5.0]: https://github.com/daimond113/pesde/compare/v0.4.7..v0.5.0%2Bregistry.0.1.0

Cargo.lock

@@ -3662,7 +3662,7 @@ checksum = "e3148f5046208a5d56bcfc03053e3ca6334e51da8dfb19b6cdc8b306fae3283e"
 
 [[package]]
 name = "pesde"
-version = "0.5.2"
+version = "0.5.3"
 dependencies = [
  "anyhow",
  "async-compression",
@@ -3706,7 +3706,7 @@ dependencies = [
 
 [[package]]
 name = "pesde-registry"
-version = "0.1.1"
+version = "0.1.2"
 dependencies = [
  "actix-cors",
  "actix-governor",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pesde"
-version = "0.5.2"
+version = "0.5.3"
 edition = "2021"
 license = "MIT"
 authors = ["daimond113 <contact@daimond113.com>"]

SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Supported Versions
+
+As pesde is currently in version 0.x, we can only guarantee security for:
+- **The latest minor** (currently 0.5).
+- **The latest release candidate for the next version**, if available.
+
+When a new minor version is released, the previous version will immediately lose security support.
+> **Note:** This policy will change with the release of version 1.0, which will include an extended support period for versions >=1.0.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.5.x   | :white_check_mark: |
+| < 0.5   | :x:                |
+
+## Reporting a Vulnerability
+
+We encourage all security concerns to be reported at [pesde@daimond113.com](mailto:pesde@daimond113.com), along the following format:
+- **Subject**: The subject must be prefixed with `[SECURITY]` to ensure it is prioritized as a security concern.
+- **Content**:
+  - **Affected Versions**: Clearly specify which are affected by the issue.
+  - **Issue Details**: Provide a detailed description of the issue, including reproduction steps and/or a simple example, if applicable. 
+
+We will try to respond as soon as possible.

docs/src/content/docs/guides/dependencies.mdx

@@ -38,17 +38,17 @@ Git dependencies are dependencies on packages hosted on a Git repository.
 
 ```toml title="pesde.toml"
 [dependencies]
-acme = { repo = "acme/package", rev = "main" }
+acme = { repo = "acme/package", rev = "aeff6" }
 ```
 
 In this example, we're specifying a dependency on the package contained within
-the `acme/package` GitHub repository at the `main` branch.
+the `acme/package` GitHub repository at the `aeff6` commit.
 
-You can also use a URL to specify the Git repository and a specific commit.
+You can also use a URL to specify the Git repository and a tag for the revision.
 
 ```toml title="pesde.toml"
 [dependencies]
-acme = { repo = "https://git.acme.local/package.git", rev = "aeff6" }
+acme = { repo = "https://git.acme.local/package.git", rev = "v0.1.0" }
 ```
 
 You can also specify a path if the package is not at the root of the repository.

docs/src/content/docs/guides/roblox.mdx

@@ -20,15 +20,15 @@ to get it added.
 Studio.
 
 Running `pesde init` will prompt you to select a target, select
-`roblox` or `roblox_server` in this case. This will setup the configuration
-needed to use pesde in a project using Rojo.
+`roblox` or `roblox_server` in this case. You will be prompted to pick out a
+scripts package. Select `pesde/scripts_rojo` to get started with Rojo.
 
 ## Usage with other tools
 
-If you are using a different sync tool, you should look for it's scripts in the
-pesde-scripts repository. If you cannot find them, you can write your own and
-optionally submit a PR to help others using the same tool as you get started
-quicker.
+If you are using a different sync tool, you should look for it's scripts
+package on the registry. If you cannot find it, you can write your own and
+optionally submit a PR to pesde-scripts to help others using the same tool as
+you get started quicker.
 
 Scaffold your project with `pesde init`, select the `roblox` or `roblox_server`
 target, and then create a `.pesde/roblox_sync_config_generator.luau` script

docs/src/content/docs/installation.mdx

@@ -41,6 +41,16 @@ You can follow the installation instructions in the
       pesde should now be installed on your system. You may need to restart your
       computer for the changes to take effect.
 
+      <Aside type="caution">
+      pesde uses symlinks which are an administrator-level operation on Windows.
+      To ensure proper functionality, enable [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development).
+      
+      
+      If you are getting errors such as `Failed to symlink file, a required
+      privilege is not held by the client`, then enabling this setting will fix
+      them.
+      </Aside>
+
       </TabItem>
       <TabItem label="Linux & macOS">
       
@@ -59,7 +69,7 @@ You can follow the installation instructions in the
       environment variable.
 
       ```sh title=".zshrc"
-      export PATH = "$PATH:/home/user/.pesde/bin"
+      export PATH="$PATH:$HOME/.pesde/bin"
       ```
 
       You should then be able to run `pesde` after restarting your shell.

docs/src/content/docs/reference/manifest.mdx

@@ -159,12 +159,13 @@ when the package is installed in order to generate the necessary configuration.
 
 **Allowed in:** `luau`, `lune`
 
-A list of scripts that will be linked to the project's `.pesde` directory, and
+A list of scripts that will be linked to the dependant's `.pesde` directory, and
 copied over to the [scripts](#scripts-1) section when initialising a project with
-this package.
+this package as the scripts package.
 
 ```toml
-scripts = { roblox_sync_config_generator = "scripts/roblox_sync_config_generator.luau" }
+[target.scripts]
+roblox_sync_config_generator = "scripts/roblox_sync_config_generator.luau"
 ```
 
 ## `[scripts]`
@@ -189,10 +190,6 @@ sync tools.
 of files specified within the [`target.build_files`](#build_files) of the
 package.
 
-You can find template scripts inside the
-[`pesde-scripts` repository](https://github.com/pesde-pkg/scripts)
-for various sync tools.
-
 <LinkCard
 	title="Roblox"
 	description="Learn more about using pesde in Roblox projects."
@@ -372,14 +369,14 @@ foo = { wally = "acme/foo", version = "1.2.3", index = "acme" }
 
 ```toml
 [dependencies]
-foo = { repo = "acme/packages", rev = "main", path = "foo" }
+foo = { repo = "acme/packages", rev = "aeff6", path = "foo" }
 ```
 
 **Git dependencies** contain the following fields:
 
 - `repo`: The URL of the Git repository.
   This can either be `<owner>/<name>` for a GitHub repository, or a full URL.
-- `rev`: The Git revision to install. This can be a branch, tag, or commit hash.
+- `rev`: The Git revision to install. This can be a tag or commit hash.
 - `path`: The path within the repository to install. If not specified, the root
   of the repository is used.
 

registry/CHANGELOG.md

@@ -5,8 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2]
+### Changed
+- Update to pesde lib API changes by @daimond113
+
+## [0.1.1] - 2024-12-19
+### Changed
+- Switch to traccing for logging by @daimond113
+
 ## [0.1.0] - 2024-12-14
 ### Added
 - Rewrite registry for pesde v0.5.0 by @daimond113
 
-[0.1.0]: https://github.com/daimond113/pesde/compare/v0.4.7..v0.5.0
+[0.1.2]: https://github.com/daimond113/pesde/compare/v0.5.2%2Bregistry.0.1.1..v0.5.3%2Bregistry.0.1.2
+[0.1.1]: https://github.com/daimond113/pesde/compare/v0.5.1%2Bregistry.0.1.0..v0.5.2%2Bregistry.0.1.1
+[0.1.0]: https://github.com/daimond113/pesde/compare/v0.4.7..v0.5.0%2Bregistry.0.1.0

registry/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pesde-registry"
-version = "0.1.1"
+version = "0.1.2"
 edition = "2021"
 repository = "https://github.com/pesde-pkg/index"
 publish = false

registry/src/endpoints/package_version.rs

@@ -71,7 +71,7 @@ pub async fn get_package_version(
 
     let (scope, name_part) = name.as_str();
 
-    let entries: IndexFile = {
+    let file: IndexFile = {
         let source = app_state.source.lock().await;
         let repo = gix::open(source.path(&app_state.project))?;
         let tree = root_tree(&repo)?;
@@ -84,14 +84,15 @@ pub async fn get_package_version(
 
     let Some((v_id, entry, targets)) = ({
         let version = match version {
-            VersionRequest::Latest => match entries.keys().map(|k| k.version()).max() {
+            VersionRequest::Latest => match file.entries.keys().map(|k| k.version()).max() {
                 Some(latest) => latest.clone(),
                 None => return Ok(HttpResponse::NotFound().finish()),
             },
             VersionRequest::Specific(version) => version,
         };
 
-        let versions = entries
+        let versions = file
+            .entries
             .iter()
             .filter(|(v_id, _)| *v_id.version() == version);
 

registry/src/endpoints/package_versions.rs

@@ -19,7 +19,7 @@ pub async fn get_package_versions(
 
     let (scope, name_part) = name.as_str();
 
-    let versions: IndexFile = {
+    let file: IndexFile = {
         let source = app_state.source.lock().await;
         let repo = gix::open(source.path(&app_state.project))?;
         let tree = root_tree(&repo)?;
@@ -32,7 +32,7 @@ pub async fn get_package_versions(
 
     let mut responses = BTreeMap::new();
 
-    for (v_id, entry) in versions {
+    for (v_id, entry) in file.entries {
         let info = responses
             .entry(v_id.version().clone())
             .or_insert_with(|| PackageResponse {

registry/src/endpoints/publish_version.rs

@@ -371,7 +371,7 @@ pub async fn publish_package(
             }
         };
 
-        let mut entries: IndexFile =
+        let mut file: IndexFile =
             toml::de::from_str(&read_file(&gix_tree, [scope, name])?.unwrap_or_default())?;
 
         let new_entry = IndexFileEntry {
@@ -386,11 +386,12 @@ pub async fn publish_package(
             dependencies,
         };
 
-        let this_version = entries
+        let this_version = file
+            .entries
             .keys()
             .find(|v_id| *v_id.version() == manifest.version);
         if let Some(this_version) = this_version {
-            let other_entry = entries.get(this_version).unwrap();
+            let other_entry = file.entries.get(this_version).unwrap();
 
             // description cannot be different - which one to render in the "Recently published" list?
             // the others cannot be different because what to return from the versions endpoint?
@@ -406,7 +407,8 @@ pub async fn publish_package(
             }
         }
 
-        if entries
+        if file
+            .entries
             .insert(
                 VersionId::new(manifest.version.clone(), manifest.target.kind()),
                 new_entry.clone(),
@@ -422,7 +424,7 @@ pub async fn publish_package(
         let reference = repo.find_reference(&refspec)?;
 
         {
-            let index_content = toml::to_string(&entries)?;
+            let index_content = toml::to_string(&file)?;
             let mut blob_writer = repo.blob_writer(None)?;
             blob_writer.write_all(index_content.as_bytes())?;
             oids.push((name, blob_writer.commit()?));

registry/src/endpoints/search.rs

@@ -68,10 +68,11 @@ pub async fn search_packages(
                 .unwrap();
             let (scope, name) = id.as_str();
 
-            let versions: IndexFile =
+            let file: IndexFile =
                 toml::de::from_str(&read_file(&tree, [scope, name]).unwrap().unwrap()).unwrap();
 
-            let (latest_version, entry) = versions
+            let (latest_version, entry) = file
+                .entries
                 .iter()
                 .max_by_key(|(v_id, _)| v_id.version())
                 .unwrap();
@@ -79,17 +80,19 @@ pub async fn search_packages(
             PackageResponse {
                 name: id.to_string(),
                 version: latest_version.version().to_string(),
-                targets: versions
+                targets: file
+                    .entries
                     .iter()
                     .filter(|(v_id, _)| v_id.version() == latest_version.version())
                     .map(|(_, entry)| (&entry.target).into())
                     .collect(),
                 description: entry.description.clone().unwrap_or_default(),
-                published_at: versions
+                published_at: file
+                    .entries
                     .values()
-                    .max_by_key(|entry| entry.published_at)
-                    .unwrap()
-                    .published_at,
+                    .map(|entry| entry.published_at)
+                    .max()
+                    .unwrap(),
                 license: entry.license.clone().unwrap_or_default(),
                 authors: entry.authors.clone(),
                 repository: entry.repository.clone().map(|url| url.to_string()),

registry/src/search.rs

@@ -104,7 +104,7 @@ pub async fn make_search(
     pin!(stream);
 
     while let Some((pkg_name, mut file)) = stream.next().await {
-        let Some((_, latest_entry)) = file.pop_last() else {
+        let Some((_, latest_entry)) = file.entries.pop_last() else {
             tracing::error!("no versions found for {pkg_name}");
             continue;
         };

src/download.rs

@@ -71,7 +71,7 @@ impl Project {
                 let version_id = version_id.clone();
                 let node = node.clone();
 
-                let span = tracing::debug_span!(
+                let span = tracing::info_span!(
                     "download",
                     name = name.to_string(),
                     version_id = version_id.to_string()

src/linking/mod.rs

@@ -254,7 +254,7 @@ impl Project {
                 let manifest = manifest.clone();
                 let package_types = package_types.clone();
 
-                let span = tracing::debug_span!(
+                let span = tracing::info_span!(
                     "link",
                     name = name.to_string(),
                     version_id = version_id.to_string()

src/main.rs

@@ -11,10 +11,9 @@ use std::{
 };
 use tempfile::NamedTempFile;
 use tracing::instrument;
-use tracing_indicatif::IndicatifLayer;
+use tracing_indicatif::{filter::IndicatifFilter, IndicatifLayer};
 use tracing_subscriber::{
-    filter::LevelFilter, fmt::time::uptime, layer::SubscriberExt, util::SubscriberInitExt,
-    EnvFilter,
+    filter::LevelFilter, layer::SubscriberExt, util::SubscriberInitExt, EnvFilter, Layer,
 };
 
 mod cli;
@@ -134,7 +133,7 @@ async fn run() -> anyhow::Result<()> {
         std::process::exit(status.code().unwrap());
     }
 
-    let indicatif_layer = IndicatifLayer::new();
+    let indicatif_layer = IndicatifLayer::new().with_filter(IndicatifFilter::new(false));
 
     let tracing_env_filter = EnvFilter::builder()
         .with_default_directive(LevelFilter::INFO.into())
@@ -147,14 +146,23 @@ async fn run() -> anyhow::Result<()> {
         .add_directive("hyper=info".parse().unwrap())
         .add_directive("h2=info".parse().unwrap());
 
+    let fmt_layer =
+        tracing_subscriber::fmt::layer().with_writer(indicatif_layer.inner().get_stderr_writer());
+
+    #[cfg(debug_assertions)]
+    let fmt_layer = fmt_layer.with_timer(tracing_subscriber::fmt::time::uptime());
+
+    #[cfg(not(debug_assertions))]
+    let fmt_layer = fmt_layer
+        .pretty()
+        .with_timer(())
+        .with_line_number(false)
+        .with_file(false)
+        .with_target(false);
+
     tracing_subscriber::registry()
         .with(tracing_env_filter)
-        .with(
-            tracing_subscriber::fmt::layer()
-                .pretty()
-                .with_writer(indicatif_layer.get_stderr_writer())
-                .with_timer(uptime()),
-        )
+        .with(fmt_layer)
         .with(indicatif_layer)
         .init();
 

src/resolver.rs

@@ -102,7 +102,7 @@ impl Project {
                         continue;
                     };
 
-                    let span = tracing::debug_span!("resolve from old graph", alias);
+                    let span = tracing::info_span!("resolve from old graph", alias);
                     let _guard = span.enter();
 
                     tracing::debug!("resolved {}@{} from old dependency graph", name, version);
@@ -131,7 +131,7 @@ impl Project {
 
                     while let Some((dep_name, dep_version, path)) = queue.pop_front() {
                         let inner_span =
-                            tracing::debug_span!("resolve dependency", path = path.join(">"));
+                            tracing::info_span!("resolve dependency", path = path.join(">"));
                         let _inner_guard = inner_span.enter();
                         if let Some(dep_node) = previous_graph
                             .get(dep_name)
@@ -399,7 +399,7 @@ impl Project {
 
                 Ok(())
             }
-                .instrument(tracing::debug_span!("resolve new/changed", path = path.join(">")))
+                .instrument(tracing::info_span!("resolve new/changed", path = path.join(">")))
                 .await?;
         }
 

src/source/pesde/mod.rs

@@ -128,7 +128,7 @@ impl PackageSource for PesdePackageSource {
             }
         };
 
-        let entries: IndexFile = toml::from_str(&string)
+        let IndexFile { entries, .. } = toml::from_str(&string)
             .map_err(|e| Self::ResolveError::Parse(specifier.name.to_string(), e))?;
 
         tracing::debug!("{} has {} possible entries", specifier.name, entries.len());
@@ -432,8 +432,20 @@ pub struct IndexFileEntry {
     pub dependencies: BTreeMap<String, (DependencySpecifiers, DependencyType)>,
 }
 
+/// The package metadata in the index file
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default)]
+pub struct IndexMetadata {}
+
 /// The index file for a package
-pub type IndexFile = BTreeMap<VersionId, IndexFileEntry>;
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
+pub struct IndexFile {
+    /// Any package-wide metadata
+    #[serde(default, skip_serializing_if = "crate::util::is_default")]
+    pub meta: IndexMetadata,
+    /// The entries in the index file
+    #[serde(flatten)]
+    pub entries: BTreeMap<VersionId, IndexFileEntry>,
+}
 
 /// Errors that can occur when interacting with the pesde package source
 pub mod errors {

src/util.rs

@@ -83,3 +83,7 @@ pub fn deserialize_git_like_url<'de, D: Deserializer<'de>>(
 pub fn hash<S: AsRef<[u8]>>(struc: S) -> String {
     format!("{:x}", Sha256::digest(struc.as_ref()))
 }
+
+pub fn is_default<T: Default + Eq>(t: &T) -> bool {
+    t == &T::default()
+}