compfuzor/apt-srctools.etc.pb at main · rektide/compfuzor · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
---
# apt-srctools -- standalone apt sources.list manipulation tools.
#
# Six zero-dependency TypeScript bins (node --strip-types, parseArgs), all
# sharing one canonical JSON source model (apt-src-model.ts). JSON is the
# standard intermediate: classic <-> json and deb822 <-> json, so any format
# pair composes through it. The scheme tool maintains single URI rows via
# block-in-file where that is possible -- see design/apt-srctools/ for the
# fidelity map and the BIF wishlist.
#
# Deployed names keep the .ts suffix: node type-stripping is extension-gated,
# and the repo convention is to run .ts directly (script/apt-tunnel-mirrors.ts
# is the precedent).
- hosts: all
  vars:
    TYPE: apt-srctools
    # node resolves module type by walking up from bin/; without this marker
    # every tool run prints a MODULE_TYPELESS_PACKAGE_JSON warning and pays
    # a re-parse. For etc-type, ETC is the deployment root itself.
    ETC_FILES:
      - name: package.json
        content: |
          {"type": "module", "private": true}
    BINS:
      # Shared model + classic/deb822 parse/emit. Library, not a command.
      - name: apt-src-model.ts
        raw: True
        mode: "0644"
      # classic (one-line .list) <-> JSON
      - name: apt-src-classic2json.ts
        raw: True
        global: True
      - name: apt-src-json2classic.ts
        raw: True
        global: True
      # deb822 (.sources) <-> JSON
      - name: apt-src-deb8222json.ts
        raw: True
        global: True
      - name: apt-src-json2deb822.ts
        raw: True
        global: True
      # Run every source file in a directory through the converters, moving
      # the dir to a specified format (classic|deb822).
      - name: apt-src-convert-dir.ts
        raw: True
        global: True
      # Toggle http <-> https on source URIs, maintaining just the URI row,
      # via block-in-file managed blocks where feasible.
      - name: apt-src-scheme.ts
        raw: True
        global: True
      # FUTURE, specified but deliberately not built (see
      # files/apt-srctools/apt-src-pin-priority.ts -- the file IS the spec):
      # retune Pin-Priority for pin stanzas matching a distribution filter
      # (forky=X sid=Y experimental=Z to start, --filter/--set later),
      # inheriting scheme's row-maintenance contract.
      - name: apt-src-pin-priority.ts
        raw: True
        global: True
    README: |
      # apt-srctools

      apt sources.list manipulation tools. All share one JSON source model;
      conversions compose through it (classic <-> json, deb822 <-> json).

      - `apt-src-classic2json.ts` / `apt-src-json2classic.ts` -- one-line
        `.list` format <-> JSON (stdin/stdout, or --file/--out).
      - `apt-src-deb8222json.ts` / `apt-src-json2deb822.ts` -- deb822
        `.sources` stanzas <-> JSON.
      - `apt-src-convert-dir.ts [--to classic|deb822] [--dry-run] [DIR]` --
        detect each source file's format in a dir (default
        /etc/apt/sources.list.d) and move it to the target format.
      - `apt-src-scheme.ts --to https|http [FILE...]` -- flip the URI scheme
        on sources, maintaining just the URI row per entry via block-in-file
        managed blocks where possible. Symlinked sources are skipped by
        default (`--follow` to edit through them): a linked file is managed
        by its deployment, and a re-render would clobber an on-disk edit.
        The pre-edit mode/owner of each file is preserved across every
        write (our writes and block-in-file's temp-file+rename alike
        derive mode from the invoking umask -- under `sudo` with umask 077
        that silently turned 0644 sources into 0600). Block provenance is
        labeled via block-in-file's `--source-label
        files/apt-srctools/apt-src-scheme.ts` option. Requires a deployed
        block-in-file version with that option; keep the two tools promoted
        together so provenance is stable.

      ## why flip to http: apt-cacher-rs

      The local apt cache (apt-cacher-rs.src.pb, :3142) can only CACHE
      plain-http client URLs: http rows are fetched-over-TLS by the proxy
      (https_upgrade_mode=Auto) and stored; https rows ride CONNECT tunnels,
      which are uncacheable passthrough. So pointing apt at the cache usefully
      -- and getting hit ratios -- means flipping every mirror that also
      serves http to `--to http`:

          apt-src-scheme.ts --to http /etc/apt/sources.list.d/<mirror>.list

      Both formats are supported for every tool here (one-line `.list` and
      deb822 `.sources`), so flipped sources and deb822-migrated sources are
      equally in scope. https-only vendors stay on tunnels (see the cacher's
      https_tunnel_allowed_mirrors).

      See design/apt-srctools/ for the JSON schema, the roundtrip fidelity
      map (what is bijective through JSON, what normalizes or is lossy), and
      the block-in-file wishlist.

      - `apt-src-pin-priority.ts` -- NOT IMPLEMENTED; the script is the
        living spec for retuning pin priorities by distribution filter
        (forky/sid/experimental to start). Run it and it says so.
  tasks:
    - import_tasks: tasks/compfuzor.includes