aRustyDev / aRustyDev/gh

feat: Add `symlink-map` action

Open
#5 0 comments 0 reactions 0 assignees View on GitHub
enhancement new-action
Dominant language
Shell
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Summary

Create a reusable GitHub Action that creates symlinks from an explicit list or mapping file.

## Use Case

After sparse-checkout-aggregate clones documentation sources, create symlinks to make them accessible to the build tool (e.g., mdbook).

## Specification

### Inputs

| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `links` | No* | — | JSON array of `{ source, target }` |
| `mapping_file` | No* | — | Path to mapping file (must match schema) |
| `source_prefix` | No | — | Prefix for source paths (with mapping_file) |
| `target_prefix` | No | — | Prefix for target paths (with mapping_file) |
| `clean` | No | `false` | Remove existing symlinks in target dirs first |

*One of `links` or `mapping_file` required.

### Example Usage

```yaml
# From job outputs (preferred)
- uses: arustydev/gha/symlink-map@v1
with:
links: ${{ steps.aggregate.outputs.symlinks }}

# OR from mapping file
- uses: arustydev/gha/symlink-map@v1
with:
mapping_file: sources.yml
source_prefix: .sources
target_prefix: books
```

### Links Format

```json
[
{ "source": ".sources/ai/docs/src", "target": "books/ai" },
{ "source": ".sources/just/docs/src", "target": "books/just" }
]
```

## Implementation Notes

- Validate source paths exist before creating symlinks
- Create parent directories for targets if needed
- Use relative symlinks where possible
- Support `clean` mode to remove stale symlinks
- Validate against schema when using mapping_file

## Schema

Schema will be published at `https://schemas.arusty.dev/gha/symlink-map/v1.schema.json`

See: arustydev/schemas for schema definition.

## Related

- Part of docs aggregation workflow extraction
- Consumes outputs from `sparse-checkout-aggregate` action
- Schema tracked in arustydev/schemas

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.