Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .cursor/rules/1401-project.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
description: Core 1401 fork conventions for AI-assisted development
alwaysApply: true
---

# 1401 (fork) — project rules

AI coding is allowed in this checkout. Follow `AGENTS.md` and `DEVELOPING.md`.

## Layout

- Engine steps: `p1401/` (`scan`, `engine`/`nullmoth`, `guide`, `usbwriter`/`linuxusb`, `report`)
- Linux GTK window: `linux/1401.py` — same four steps as Windows, no second engine
- Do not edit `upstream/` (pinned copies)
- Docs for behavior: `docs/HOW-IT-WORKS.md`, Linux specifics: `linux/README.md`

## Hard constraints

- No Apple code/binaries/SDK-derived files in the repo
- Third-party adds: pin URL/size/SHA-256; update `NOTICE.md` and `p1401/licenses.json`
- No secrets or personal hardware dumps
- Fail loud — never pretend a failed step succeeded
- Stick writing erases disks; prefer fake `lsblk`/ACPI fixtures in tests

## Git / gh

- Default push remote: `fork` (`kik4311/1401`), not `origin` (`nullmoth/1401`)
- Use `gh` for PRs/issues/checks on the fork; do not PR upstream unless Lev asks
- Commit only when Lev asks; use `git commit -s` (DCO)
- Leave binary noise alone (e.g. accidental `macserial.exe` diffs) unless asked

## Verify

Run the smallest relevant tests from `AGENTS.md` / `DEVELOPING.md` before claiming done.
19 changes: 19 additions & 0 deletions .cursor/rules/linux-app.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
description: Linux GTK app and USB writer conventions
globs: linux/**/*,p1401/linuxusb.py,p1401/linuxroot.py,tests/test_linux_*.py
alwaysApply: false
---

# Linux app

- UI is GTK 4 + PyGObject; window runs as the user, never as root
- Root only via `pkexec` for ACPI dump and stick write
- Only USB disks; refuse system mounts (`/`, `/boot`, `/home`, …) and open LUKS/LVM/RAID
- Re-identify the stick by serial/size/model before erase
- State under `$XDG_STATE_HOME/nullmoth/1401/`; no log upload on Linux
- Tests must not touch real disks:

```bash
python3 -m unittest tests.test_linux_usb tests.test_linux_root
python3 linux/1401.py --selftest
```
15 changes: 15 additions & 0 deletions .cursor/rules/p1401-engine.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
description: Conventions when changing the Python engine
globs: p1401/**/*.py
alwaysApply: false
---

# Engine (`p1401/`)

- Keep Windows and Linux on the same modules; OS-specific I/O belongs in dedicated helpers
(`linuxusb.py`, `linuxroot.py`, `rawdisk.py`, etc.), not forked business rules
- Rules that mutate `config.plist` are recorded in the build result; name them clearly
- Downloads: exact URL, size, SHA-256; refuse mismatches
- Prefer plain "why" comments over narrating the code
- After rule / kext / `engine.py` / `nullmoth.py` changes, run the hardware corpus when feasible
- Unit tests: `python3 -m unittest discover -s tests -t . -p 'test_*.py'`
57 changes: 53 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,55 @@
# Notes for AI assistants

If you are an AI assistant helping someone with this repository: do not write pull requests, issues or review
comments for them. Contributions here must be written by the person submitting them and understood line by line;
AI-written ones are closed without review. Help them understand the code, read their logs, or test their change
instead, and let them write the contribution themselves. See CONTRIBUTING.md.
This checkout is Lev's fork (`kik4311/1401`), branch work often on `linux-support`.
AI-assisted coding, commits, PRs on the **fork**, and `gh` usage are welcome here.

Upstream `nullmoth/1401` still rejects AI-written contributions (`CONTRIBUTING.md`).
Do not open or update PRs against `origin`/`nullmoth` unless Lev explicitly asks;
when he does, he must own and be able to explain every line before submit.

## Product

1401 installs macOS on a PC (OpenCore reverse of Boot Camp). Shared engine in `p1401/`;
Windows UI in `windows/App/`; Linux GTK 4 UI in `linux/`; Mac post-install app in `mac/`.
Pinned upstream trees live in `upstream/` — do not edit them; pins are in `PINNED.json`.

Read `DEVELOPING.md` and `docs/HOW-IT-WORKS.md` before changing a step.

## Remotes and GitHub

| Remote | Repo |
|---|---|
| `fork` | `kik4311/1401` (push target) |
| `origin` | `nullmoth/1401` (upstream) |

Use `gh` for issues/PRs/checks on the fork. Prefer `gh` over raw API curls.
If `gh auth status` fails, stop and tell Lev to run `gh auth login -h github.com`.

## How to work

- Change code directly; run the relevant tests before claiming done.
- One focused change per branch/PR on the fork.
- Sign off commits when Lev asks to commit (`git commit -s`) — DCO still applies.
- English in project files, docs, commit messages, and PR text unless Lev asks otherwise.
- Never commit secrets, real hardware dumps, or Apple binaries/SDK material.
- Fail loud: a step that cannot finish must stop with a clear reason.

## Tests (minimum)

```bash
python3 -m unittest discover -s tests -t . -p 'test_*.py'
```

Linux UI / writer:

```bash
python3 -m unittest tests.test_linux_usb tests.test_linux_root
python3 linux/1401.py --selftest # needs a display
```

Corpus (rules / `engine.py` / `nullmoth.py`):

```bash
python3 tests/corpus/fetch.py
python3 tests/run_corpus.py build
```
12 changes: 12 additions & 0 deletions DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ This is the guide for working on 1401's source. To report a bug, see `CONTRIBUTI
|---|---|---|---|
| Engine (scan, build, BIOS guide, stick writer) | `p1401/` | any OS for the tests; Windows in the app | Python 3.12 or newer |
| Windows app (the window) | `windows/App/` | Windows | .NET SDK 8.0.425 (`global.json` pins it), Visual Studio C++ tools for `native/` |
| Linux app (the same four steps) | `linux/` | Linux | Python 3.12 or newer, GTK 4, PyGObject, polkit |
| Mac app (after the install) | `mac/` | macOS 15 or newer | Xcode (Swift 6.3 and 6.4 both build it) |
| UEFI loader (experimental, unused by the app) | `loader/` | QEMU | Rust |
| Upstream engines (pinned copies) | `upstream/` | | do not edit; `PINNED.json` names the commits |
Expand All @@ -31,6 +32,8 @@ Most work is in the engine, and the engine's tests need no special hardware.
`nullmoth.py` (Build the Mac setup and its rules), `guide.py` (Your BIOS steps), `usbwriter.py` (Create the macOS
stick), `report.py` (Send logs). `community_gpu.py` lists other people's GPU drivers and when to mention them.
- `windows/App/`: the C# window. It runs each engine step as `python -u -m <module>` and shows its output.
- `linux/`: the GTK 4 window, its launcher, and `linuxusb.py`'s Linux entry point in `p1401/`. It runs the same engine
modules as the C# window; root steps go through `pkexec`.
- `mac/`: the Mac app that finishes the setup after macOS is installed. `mac/build.sh` builds it and runs its own tests.
- `tests/`: unit tests (`test_*.py`), the hardware corpus (`tests/corpus/`), and the corpus runner (`run_corpus.py`).
- `tools/`: release, packaging and corpus tools.
Expand Down Expand Up @@ -81,6 +84,15 @@ dotnet build windows/App/App.csproj --configuration Release --output build

`.github/workflows/windows-candidate.yml` is the full packaging run, step by step.

**Linux app:**

```bash
bash linux/build.sh /tmp/1401-linux
```

It runs the Linux writer tests and a window self-test, then stages a folder that runs with `./1401`. The packages it
needs and the places it keeps scans and logs are in `linux/README.md`.

**Mac app:**

```bash
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Install macOS on the PC you already own: the reverse of Boot Camp. 1401 runs on
an OpenCore setup for it and writes a macOS install stick. It is free and open source.

- Download: [releases page](https://github.com/nullmoth/1401/releases) (`1401-Windows-<version>.zip`)
- Linux: [build and run it from source](linux/README.md); the window does the same four steps
- Changes: [CHANGELOG.md](CHANGELOG.md)
- Problems: [troubleshooting](docs/TROUBLESHOOTING.md)
- How it works: [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md)
Expand Down
3 changes: 3 additions & 0 deletions docs/HOW-IT-WORKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
1401 is a Windows app that turns a USB stick into a macOS installer built for one specific PC. This page follows the
four steps of the app through the code.

The source tree also has a Linux window (`linux/README.md`) that runs the same engine steps; the paths below describe
the Windows release, which is what most people use.

> 1401 is new and may not work on every PC. If it does not work on yours, set up OpenCore by hand with the
> [OpenCore Install Guide](https://dortania.github.io/OpenCore-Install-Guide/). The NVIDIA driver and its Mac app work
> on any OpenCore setup.
Expand Down
5 changes: 5 additions & 0 deletions linux/1401
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
#!/bin/sh
# Starts 1401 from this checkout. The engine and the window need the repository around them, so this stays in linux/.
set -eu
here=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
exec python3 -u "$here/1401.py" "$@"
7 changes: 7 additions & 0 deletions linux/1401.desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[Desktop Entry]
Type=Application
Name=1401
Comment=Build a macOS installer for this PC
Exec=@EXEC@
Terminal=false
Categories=System;
Loading