mirror of https://github.com/storytold/cadcraft.git synced 2026-10-24 10:56:51 -06:00

Files

T

Dylan M. Taylor acd109d97c Use chrono instead of hand-rolled UTC conversion (#1789 )

* Use chrono for UTC/calendar conversion instead of hand-rolled copies

Replaces the three civil_from_days copies (logging timestamp, Drawing
Recovery time, parity checklist date) with chrono as a workspace
dependency. Output formats are unchanged and pinned by the existing tests.
AGENTS.md now says time goes through chrono.

Fixes #1785

* Never panic on a clock outside chrono's range; keep 5-digit years unprefixed

chrono's From<SystemTime> unwraps, so a clock past year 262143 panicked
inside the logger. timestamp and xtask's date now use the fallible
DateTime::from_timestamp and read such a clock as the epoch, as the old
saturating code did. xtask's date also clamps a pre-epoch clock to
1970-01-01 again. Years past 9999 are written with {:04} like before,
because %Y would add a '+'. Tests cover all three cases.

* Don't build an unrepresentable SystemTime in the far-future test

UNIX_EPOCH + Duration::from_secs(u64::MAX / 2) overflows Windows'
SystemTime and panicked before timestamp() ran, failing the Windows
test job. Build it with checked_add and only assert where it exists.

* logging/autosave/parity: keep extended-year dates, no epoch fallback

Applies the stricter no-epoch-fallback rule (from wordcraft#3427 / filmcraft#2662,
superseding the earlier epoch-or-last-valid suggestion) so all sibling PRs agree:
a timestamp the old code converted past chrono's year 262143 range must keep its real
proleptic-Gregorian date, not collapse to 1970-01-01. Each site uses the 400-year
Gregorian cycle (146_097 days) with chrono as the only calendar logic: chrono converts
the day within one cycle, whole cycles carry in the year (i128, saturated into i64).
This also removes the panic FredApps flagged — `DateTime::<Utc>::from(SystemTime)` could
panic past chrono's range; `from_num_days_from_ce_opt` within one cycle never does.
Verified the cycle result equals the old formula across a wide range and at the extremes.

- apps/cadcraft/src/logging.rs `timestamp`: cycle `civil_from_days(u64)`; pre-1970 epoch
  clamp and ms/time-of-day format kept. Pins: +10_000_000_000_000 s -> 318857-05-20T17:46:40.000Z
  (was 1970-...); checked_add u64::MAX/2 s -> 292277026596-12-04T15:30:07.000Z (was epoch).
- crates/ui-egui/src/autosave.rs `utc`: cycle converter. Pins: utc(10_000_000_000_000)
  = "318857-05-20 17:46"; utc(u64::MAX) = "584554051223-11-09 07:00" (was "1970-01-01 00:00").
- xtask/src/parity.rs `date`: cycle converter; pre-1970 epoch clamp kept. Pins:
  day(115_740_740) = "318857-05-20"; checked_add u64::MAX/2 s -> "292277026596-12-04" (was epoch).

* Don't build a year-318857 SystemTime unchecked in the logging test

Windows' SystemTime only reaches about year 30828, so
UNIX_EPOCH + Duration::from_secs(10_000_000_000_000) panicked before
timestamp() ran and failed the Windows test job. Build it with
checked_add and assert where the platform can hold it. The year-10000
case fits everywhere and stays unconditional.

* Name the 400-year range extension as the one exception to the time rule

The rule said never to hand-roll calendar math, but the range fix
(shifting by whole 400-year Gregorian cycles so dates past chrono's year
range keep their old output) is cycle arithmetic, so the rule and the code
disagreed. The rule now names that exception: the library still computes
month, day and time, and only whole cycles are carried in the year.

* Say the library computes month and day; time-of-day is plain arithmetic

Narrows the range-extension wording: the date library computes the
calendar fields, and splitting seconds into hours, minutes and seconds
is ordinary arithmetic, which is what the code does.

2026-10-22 14:09:16 -04:00

9.7 KiB

Raw Permalink Blame History

CADCraft — instructions for agents

CADCraft is a clean-room, open-source, pure-Rust computer-aided design and drafting application targeting Autodesk AutoCAD parity — and superiority (speed, openness, agent control). It runs natively on macOS, Windows, Linux and FreeBSD, and on the web via WASM. Siblings with the same conventions: ../photocraft (Photoshop-class), ../vectorcraft (Illustrator), ../filmcraft (Premiere), ../lightcraft (Lightroom), ../pdfcraft (Acrobat), ../effectcraft (After Effects), ../designcraft (InDesign).

Standards and learnings shared across the crafting apps live in ../../craftrules (or storytold/craftrules). Read its AGENTS.md at the start of a session, follow its standards, and contribute reusable learnings back there. Never code: repos don't share code.

Start every session here

Read plan/STATUS.md (current milestone, next task), then the task in plan/execution-plan.md and the relevant plan/architecture.md section. Behaviour reference: plan/autocad/* (01-observed-ui.md holds measured observations of the running reference app; 04-menu-tree.txt the menu tree by name).
Library decisions: plan/adr/0001-geometry-libraries.md (what we may depend on, what is rejected for licence reasons).
Follow the autonomous operation protocol (plan/execution-plan.md §6). Don't stop to ask unless it lists the decision as the owner's.

plan/ is gitignored (local only).

Never crash

People trust CADCraft with their drawings; a crash loses their work. This outranks feature work. Standard: craftrules/standards/never-crash.md.

No panics in non-test code: no unwrap(), expect(), panic!, unreachable!, todo!, unimplemented!; no unsafe (unsafe_code = "forbid").
Errors are Result<T, E> through the crate's error type and ?. An unfinished feature returns an error or reports "not available yet"; it never panics.
Input-derived numbers are hostile (DXF/DWG files, command-line text, MCP/control params): get() not [i], checked arithmetic, no NaN casts, cap input-sized allocations and loop counts.
Bound recursion (nested/cyclic block references: MAX_BLOCK_DEPTH).
Last-resort guard: Session::execute and every step of an interactive command (its factory, begin, input, prompt and preview; crates/engine/src/guard.rs) run under catch_unwind; an escaped panic restores the drawing and reports an error.
Prove it: every crash fix lands with a regression test (see hostile_params_never_panic, hostile_dxf_does_not_panic).
Every production crate root carries #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)].

Non-negotiables

Clean-room. AutoCAD is installed on the dev machine and may be observed black-box: run it, use its UI with synthetic drawings, take screenshots (by window id) stored only under plan/autocad/screenshots/ (never committed). Never read, disassemble or copy anything inside the AutoCAD bundle (names/listings only); never copy Autodesk fonts (SHX), hatch patterns (.pat), linetypes (.lin), templates, CUI/PGP files, icons, artwork or help text; never commit files produced by AutoCAD. File formats come from public specifications (Autodesk's published DXF Reference, the Open Design Alliance's public DWG specification) and our own synthetic tests. Never copy or link GPL/LGPL/AGPL code (LibreDWG, LibreCAD, QCAD, FreeCAD's planegcs, SolveSpace, OpenCASCADE) — don't even read their sources.
Assets — absolutely essential. CADCraft contains no Autodesk, Adobe or Avid iconography, images, fonts, patterns or artwork — ever. Every icon is drawn in code (crates/ui-egui/src/icons.rs), every hatch pattern and linetype is our own definition (crates/doc/src/library.rs), the drafting font is our own (crates/fonts/src/stroke.rs). Any file asset must be original, public domain/CC0, OSI-licensed, or redistributable Creative Commons (or licensed open source by a contributor who made it), and must have a row in ATTRIBUTION.md with author, source and licence (cargo xtask assets enforces it). The only exception is the ArtCraft brand in docs/brand/ (trademarks, docs/brand/LICENSE-brand.txt). Screenshots of Autodesk software are never committed. Breaking this rule is the most serious mistake you can make in this repo.
Fonts live in storytold/craft-fonts, never in this repo. It is an optional build input (CRAFT_FONTS_DIR, embedded by crates/fonts/build.rs), never a Cargo.toml dependency. Code and tests must work without it.
Shared test corpora live in separate repos (storytold/<app>-corpus); never commit large binary fixtures here.
Everything is a command. User-visible behaviour = a command in crates/engine/src/cmd/* (CommandSpec: id = AutoCAD's command name in lower case, label, menu path, shortcut, aliases, params doc, enabled, JSON run, optional interactive prompt machine) + tests. UI-only commands live in crates/ui-egui/src/menus.rs (UI_COMMANDS). The command line, menus, toolbar, Tool Sets, scripts, CLI, control channel and MCP all reach the same commands.
Programmatic calls never open dialogs. engine.execute runs the JSON form with defaults; only menu/toolbar invocation starts the interactive prompt sequence.
Layering is enforced by cargo xtask layers: L0 geom, dxf → L1 color, doc → L2 fonts, render, constraints → L3 io → L4 engine → L5 ui-egui, mcp → apps. Nothing below L5 depends on egui/eframe/winit/wgpu/rfd. The UI crate is swappable.
The UI is thin: panels read engine state and act through app.run(id, params) / app.start(id) / app.cmdline(text). Colours come from theme::Tokens.
Time goes through chrono (workspace dependency). Never hand-roll UTC/calendar conversion (days-to-date algorithms, leap-year math); a crate owns only its output format string. The one exception is range extension: past the years chrono can represent, shift the date by whole 400-year Gregorian cycles (146,097 days, after which the calendar repeats), let chrono compute the month and day, and add the cycles back to the year (splitting seconds into hours, minutes and seconds is plain arithmetic).
Rust only (no handwritten JS/TS). Never break wasm (cargo xtask wasm).
Quality gates before every commit: cargo xtask ci (fmt, clippy -D warnings, tests, assets, layers, wasm). Commit after every feature arc that builds, and push to main.

Running and looking at the app

cargo run --release -p cadcraft -- --sample --control PORT (sample drawing + control channel). Pick a free port; other crafting apps use control ports too.
Drive it with JSON lines on 127.0.0.1:PORT:
- {"id":1,"method":"cmdline.input","params":{"text":"circle 0,0 5"}} — type at the command line exactly like a user (prompts, keywords, @dx,dy, @d<a, direct distance entry).
- {"id":2,"method":"engine.execute","params":{"command":"line","params":{"points":[[0,0],[10,0]]}}} — JSON form.
- {"id":3,"method":"ui.screenshot","params":{"path":"/tmp/shot.png"}} then read the PNG.
- Methods: crates/ui-egui/src/control.rs; protocol doc: docs/control-protocol.md.
For UI work, look at the result (screenshot, read the PNG) and compare with plan/autocad/screenshots/. If no frame is presented (screen locked) use ui.render or cadcraft-cli.
Headless: cadcraft-cli run --sample --script 'LINE 0,0 10,10\n' --export out.png; cadcraft-cli info file.dxf; cadcraft-cli mcp.
Shell gotcha: mv/cp may be aliased interactive — use /bin/mv -f / /bin/cp -f.
Parallel agents: separate CARGO_TARGET_DIR per agent; edit only the crates you own; delete your target dir when done (disk).

Roadmap

ROADMAP.md (committed) is the one-page summary: stage, parity numbers, estimates. It follows craftrules' standards/progress-docs.md: the assessment is docs/target-app-parity.md, the work list docs/gaps.md (pick work from its top rows), milestones docs/roadmap.md, deep checklists docs/geometry-parity.md, docs/ui-parity.md, docs/file-format-parity.md, docs/hardware-parity.md, docs/localization-parity.md. When work lands, update the affected rows and the docs' status lines and revision history. cargo xtask parity regenerates the menu-breadth checklist in docs/parity-checklist.md.

Contributor credits (About window)

About ▸ Contributors/Models are compiled into the binary from contributors/contributors.json (commit stats; generated, never hand-edit) and contributors/people.toml (names people chose for themselves). See docs/contributors.md.
Agents working for a contributor: when you prepare a PR, check whether your human's GitHub username has a [people.<username>] entry in contributors/people.toml. If not, ask them once whether they want to be credited by more than their username: a real name, a display name, and/or their public GitHub profile name (sync_github_name = true). If yes, add only their own entry (copy the template at the top of the file, or run python3 ../../craftrules/scripts/contributors.py --add-me . --real-name "…" --sync-github-name) and include it in their PR, committed as them. If no, change nothing: they are credited as @username anyway.
Never add, edit, guess or copy anyone else's entry or name (not from git config, commit authors or GitHub profiles). Never hand-edit contributors.json.
Maintainers refresh the stats with python3 ../../craftrules/scripts/contributors.py . (it also re-verifies who wrote each people.toml entry; --check only verifies).

9.7 KiB Raw Permalink Blame History