From 9ecb521c73d5e3ad67079612f3f33d8084fcb770 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:34:44 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 165 ------------------------------------------------ README.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 177 insertions(+), 165 deletions(-) delete mode 100644 README.adoc create mode 100644 README.md diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 3da7264..0000000 --- a/README.adoc +++ /dev/null @@ -1,165 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= JanusKey -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=openssourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/januskey"] - - -image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] - - -Jonathan D.A. Jewell -:toc: macro -:icons: font -:source-highlighter: rouge -:experimental: -:url-github: https://github.com/hyperpolymath/januskey -:url-gitlab: https://gitlab.com/hyperpolymath/januskey -:url-bitbucket: https://bitbucket.org/hyperpolymath/januskey -:url-codeberg: https://codeberg.org/hyperpolymath/januskey - -*Reversible File Operations (formal proofs pending) Through Maximal Principle Reduction* - -image:https://img.shields.io/badge/RSR-Certified-gold[RSR Certified,link=https://github.com/hyperpolymath/rhodium-standard-repositories] - -toc::[] - -== Overview - -JanusKey is a file operation utility suite that pursues complete reversibility through architectural design rather than logging or backups. Unlike traditional backup systems that restore from external state, JanusKey operations carry sufficient information for inversion — the goal is to make data loss architecturally impossible (formal proofs pending). - -=== Key Features - -* *Reversible by design* - Every operation carries inversion metadata (formal proofs pending) -* *Instant Rollback* - Undo changes in milliseconds -* *Data loss impossible by construction* - the architectural goal the pending proofs are to establish -* *Complete Audit Trail* - Every change tracked automatically -* *Transaction Support* - Group operations, commit/rollback together -* *Content-Addressed Storage* - SHA256 hashing with deduplication - -== Quick Start - -[source,bash] ----- -# Build from source (requires Rust) -cd src/januskey -cargo build --release - -# Initialize JanusKey in your project -jk init - -# Delete files (reversible) -jk delete *.log - -# Undo the delete -jk undo - -# Transactions for batch operations -jk begin -jk delete temp*.txt -jk modify "s/DEBUG/INFO/g" config.yaml -jk preview # Review changes -jk commit # Or: jk rollback ----- - -== Commands - -[cols="1,3"] -|=== -| Command | Description - -| `jk init` | Initialize JanusKey in current directory -| `jk delete ` | Delete files (reversible) -| `jk modify ` | Modify files with sed-like syntax -| `jk move ` | Move/rename files -| `jk copy ` | Copy files -| `jk undo [--count N]` | Undo last operation(s) -| `jk begin [name]` | Start a transaction -| `jk commit` | Commit current transaction -| `jk rollback` | Rollback current transaction -| `jk preview` | Preview pending changes -| `jk history` | Show operation history -| `jk status` | Show current status -|=== - -== Architecture - -JanusKey implements *Maximal Principle Reduction (MPR)*, a security methodology where vulnerability elimination occurs by construction rather than verification. - ----- -+----------------------------+ -| JanusKey CLI | <-- jk delete, jk modify, jk move -+----------------------------+ -| Operation Layer | <-- Generates inverse metadata -+----------------------------+ -| Transaction Manager | <-- Groups ops, commit/rollback -+----------------------------+ -| Metadata Store | <-- Append-only operation log -+----------------------------+ -| Content-Addressed Storage | <-- SHA256, deduplication -+----------------------------+ ----- - -=== Reversibility Guarantee - -Every operation stores sufficient metadata for perfect inversion: - -* *Delete*: Stores full content + metadata for restoration -* *Modify*: Stores original content hash for rollback -* *Move*: Stores original path for unmove -* *Copy*: Destination path for deletion - -== Installation - -=== From Source (Rust) - -[source,bash] ----- -# Clone the repository -git clone {url-github} -cd januskey/src/januskey - -# Build release binary -cargo build --release - -# Install to PATH -cargo install --path . ----- - -== Mirrors - -[cols="1,2"] -|=== -| Platform | URL - -| GitHub (primary) | {url-github} -| GitLab | {url-gitlab} -| Bitbucket | {url-bitbucket} -| Codeberg | {url-codeberg} -|=== - -== License - -This project is licensed under the Mozilla Public License, v. 2.0. See the `LICENSE` file for details. - -SPDX-License-Identifier: CC-BY-SA-4.0 - -== Contributing - -See link:CONTRIBUTING.md[CONTRIBUTING.md]. - -== Research - -JanusKey is based on research into reversible computing (formal proofs are a target, not yet complete) and Maximal Principle Reduction. See the white paper in `docs/` for formal proofs and theoretical foundations. - -== Metadata - -* Domain: software-development -* Framework: RSR (Rhodium Standard Repository) -* Language: Rust -* Dublin Core: link:.well-known/dc.xml[.well-known/dc.xml] - - -== Architecture - -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c3964f2 --- /dev/null +++ b/README.md @@ -0,0 +1,177 @@ + + +[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0) +[![Palimpsest](https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg)](https://github.com/hyperpolymath/palimpsest-license) + +Jonathan D.A. Jewell \<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\> +:toc: macro :icons: font :source-highlighter: rouge :experimental: +:url-github: :url-gitlab: + :url-bitbucket: + :url-codeberg: + + +**Reversible File Operations (formal proofs pending) Through Maximal +Principle Reduction** + +[![RSR Certified](https://img.shields.io/badge/RSR-Certified-gold)](https://github.com/hyperpolymath/rhodium-standard-repositories) + +
+ +
+ +# Overview + +JanusKey is a file operation utility suite that pursues complete +reversibility through architectural design rather than logging or +backups. Unlike traditional backup systems that restore from external +state, JanusKey operations carry sufficient information for inversion — +the goal is to make data loss architecturally impossible (formal proofs +pending). + +## Key Features + +- **Reversible by design** - Every operation carries inversion metadata + (formal proofs pending) + +- **Instant Rollback** - Undo changes in milliseconds + +- **Data loss impossible by construction** - the architectural goal the + pending proofs are to establish + +- **Complete Audit Trail** - Every change tracked automatically + +- **Transaction Support** - Group operations, commit/rollback together + +- **Content-Addressed Storage** - SHA256 hashing with deduplication + +# Quick Start + +```bash +# Build from source (requires Rust) +cd src/januskey +cargo build --release + +# Initialize JanusKey in your project +jk init + +# Delete files (reversible) +jk delete *.log + +# Undo the delete +jk undo + +# Transactions for batch operations +jk begin +jk delete temp*.txt +jk modify "s/DEBUG/INFO/g" config.yaml +jk preview # Review changes +jk commit # Or: jk rollback +``` + +# Commands + +| Command | Description | +|----|----| +| `jk` `init` | Initialize JanusKey in current directory | +| `jk` `delete` `` | Delete files (reversible) | +| `jk` `modify` `` `` | Modify files with sed-like syntax | +| `jk` `move` `` `` | Move/rename files | +| `jk` `copy` `` `` | Copy files | +| `jk` `undo` `[--count` `N]` | Undo last operation(s) | +| `jk` `begin` `[name]` | Start a transaction | +| `jk` `commit` | Commit current transaction | +| `jk` `rollback` | Rollback current transaction | +| `jk` `preview` | Preview pending changes | +| `jk` `history` | Show operation history | +| `jk` `status` | Show current status | + +# Architecture + +JanusKey implements **Maximal Principle Reduction (MPR)**, a security +methodology where vulnerability elimination occurs by construction +rather than verification. + + +----------------------------+ + | JanusKey CLI | <-- jk delete, jk modify, jk move + +----------------------------+ + | Operation Layer | <-- Generates inverse metadata + +----------------------------+ + | Transaction Manager | <-- Groups ops, commit/rollback + +----------------------------+ + | Metadata Store | <-- Append-only operation log + +----------------------------+ + | Content-Addressed Storage | <-- SHA256, deduplication + +----------------------------+ + +## Reversibility Guarantee + +Every operation stores sufficient metadata for perfect inversion: + +- **Delete**: Stores full content + metadata for restoration + +- **Modify**: Stores original content hash for rollback + +- **Move**: Stores original path for unmove + +- **Copy**: Destination path for deletion + +# Installation + +## From Source (Rust) + +```bash +# Clone the repository +git clone {url-github} +cd januskey/src/januskey + +# Build release binary +cargo build --release + +# Install to PATH +cargo install --path . +``` + +# Mirrors + +| Platform | URL | +|------------------|-----------------| +| GitHub (primary) | {url-github} | +| GitLab | {url-gitlab} | +| Bitbucket | {url-bitbucket} | +| Codeberg | {url-codeberg} | + +# License + +This project is licensed under the Mozilla Public License, v. 2.0. See +the `LICENSE` file for details. + +SPDX-License-Identifier: CC-BY-SA-4.0 + +# Contributing + +See CONTRIBUTING. + +# Research + +JanusKey is based on research into reversible computing (formal proofs +are a target, not yet complete) and Maximal Principle Reduction. See the +white paper in `docs/` for formal proofs and theoretical foundations. + +# Metadata + +- Domain: software-development + +- Framework: RSR (Rhodium Standard Repository) + +- Language: Rust + +- Dublin Core: .well-known/dc.xml + +# Architecture + +See TOPOLOGY for a visual +architecture map and completion dashboard.