codexport 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +158 -0
  3. package/dist/index.js +746 -0
  4. package/docs/prd.md +434 -0
  5. package/package.json +55 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Microck
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,158 @@
1
+ <h1 align="center">codexport</h1>
2
+
3
+ <p align="center">
4
+ <a href="https://www.npmjs.com/package/codexport"><img src="https://img.shields.io/npm/v/codexport?style=flat-square&label=npm&color=000000" alt="npm badge"></a>
5
+ <a href="https://www.npmjs.com/package/codexport"><img src="https://img.shields.io/npm/dt/codexport?style=flat-square&label=downloads&color=000000" alt="npm downloads"></a>
6
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-mit-000000?style=flat-square" alt="license badge"></a>
7
+ </p>
8
+
9
+ ---
10
+
11
+ `codexport` replicates a canonical Machine1 Codex setup to follower machines. it is built for operators who want one trusted `~/.codex` source of truth, follower-local overlays, and a low-friction `npx` join path without committing plaintext secrets to GitHub.
12
+
13
+ Machine1 serves a content-hashed bundle from its `~/.codex` directory. followers pin the master's fingerprint on join, fetch updates over a Tailscale-reachable HTTP address, and apply updates at Codex `SessionStart` through a short best-effort hook.
14
+
15
+ [npm](https://www.npmjs.com/package/codexport) | [github](https://github.com/Microck/codexport)
16
+
17
+ ## why
18
+
19
+ if you keep a carefully tuned Codex setup on one machine and want the same defaults elsewhere, `codexport` gives you a practical pull-based sync path.
20
+
21
+ - keep Machine1 as the canonical Codex configuration source
22
+ - let followers preserve local MCPs, local skills, trust entries, and path overrides
23
+ - sync auth-bearing files through the private Tailscale path instead of a plaintext GitHub commit
24
+ - refresh followers at Codex session startup without interrupting active sessions
25
+ - use content-hash revisions and pinned master fingerprints instead of blind file copies
26
+
27
+ ## quickstart
28
+
29
+ `codexport` requires Node.js 20+.
30
+
31
+ on Machine1:
32
+
33
+ ```bash
34
+ npx codexport master init
35
+ npx codexport master service install
36
+ npx codexport master link --host machine1.tailnet.ts.net
37
+ ```
38
+
39
+ on a follower:
40
+
41
+ ```bash
42
+ npx codexport follower join "codexport://join?host=machine1.tailnet.ts.net&port=17342&fingerprint=..."
43
+ npx codexport hook install
44
+ ```
45
+
46
+ manual sync remains available:
47
+
48
+ ```bash
49
+ npx codexport sync --apply
50
+ npx codexport status
51
+ ```
52
+
53
+ ## sync model
54
+
55
+ ```text
56
+ Machine1 ~/.codex
57
+ -> codexport master serve
58
+ -> Tailscale-reachable HTTP bundle
59
+ -> follower sync/apply
60
+ -> generated follower ~/.codex
61
+ ```
62
+
63
+ followers trust the provided Tailscale address and store the master fingerprint. later syncs refuse changed fingerprints by default, so a changed master identity requires intentional re-enrollment.
64
+
65
+ ## included state
66
+
67
+ the master bundle includes canonical Codex config, auth files, hooks, prompts,
68
+ rules, skills, skill libraries, `AGENTS.md`, `RTK.md`, and `mise.toml` when
69
+ present.
70
+
71
+ runtime state such as logs, caches, sessions, history, compact handoffs, and
72
+ SQLite databases is excluded.
73
+
74
+ ## local follower state
75
+
76
+ follower-local state lives under `~/.codexport`:
77
+
78
+ ```text
79
+ ~/.codexport/local.toml
80
+ ~/.codexport/mcps.local.toml
81
+ ~/.codexport/skills/
82
+ ~/.codexport/overrides/
83
+ ```
84
+
85
+ canonical MCP and skill names win by default. same-name local MCPs or skills
86
+ fail unless explicitly allowed in `local.toml`:
87
+
88
+ ```toml
89
+ allowMcpOverrides = ["local-name"]
90
+ allowSkillOverrides = ["local-skill"]
91
+
92
+ [pathVariables]
93
+ workspaceRoot = "D:/workspace"
94
+ ```
95
+
96
+ path variables in canonical config such as `${workspaceRoot}` are expanded from
97
+ the follower's `local.toml` before writing the generated `~/.codex/config.toml`.
98
+
99
+ ## command surface
100
+
101
+ | command | purpose |
102
+ | --- | --- |
103
+ | `codexport master init` | create or refresh Machine1 master identity and bundle state |
104
+ | `codexport master serve` | serve the current canonical bundle over HTTP |
105
+ | `codexport master link` | print a durable follower join link and fallback command |
106
+ | `codexport master rebuild` | force rebuild the master bundle for repair/debugging |
107
+ | `codexport master service install` | install the user-level master background service |
108
+ | `codexport follower join` | enroll a follower from a join link or explicit master URL |
109
+ | `codexport sync` | fetch the latest master bundle |
110
+ | `codexport apply` | apply the last staged bundle |
111
+ | `codexport hook install` | install the follower-only Codex `SessionStart` hook |
112
+ | `codexport status` | report role, master URL, fingerprint, revision, and reachability |
113
+
114
+ ## platform support
115
+
116
+ | platform | master service | follower hook | manual sync |
117
+ | --- | --- | --- | --- |
118
+ | linux with systemd user services | supported | supported | supported |
119
+ | windows 10/11 scheduled tasks | supported | supported | supported |
120
+
121
+ followers do not need a background service in v1. the hook runs a short best-effort sync at Codex session startup, and `codexport sync --apply` is available when an immediate refresh is needed.
122
+
123
+ ## examples
124
+
125
+ generate a copy-paste join command:
126
+
127
+ ```bash
128
+ codexport master link --host machine1.tailnet.ts.net
129
+ ```
130
+
131
+ join with explicit trust metadata:
132
+
133
+ ```bash
134
+ codexport follower join \
135
+ --master http://machine1.tailnet.ts.net:17342 \
136
+ --fingerprint <fingerprint> \
137
+ --apply
138
+ ```
139
+
140
+ check current follower state:
141
+
142
+ ```bash
143
+ codexport status
144
+ ```
145
+
146
+ ## development
147
+
148
+ ```bash
149
+ npm install
150
+ npm run typecheck
151
+ npm test
152
+ npm run build
153
+ npm pack --dry-run
154
+ ```
155
+
156
+ ## license
157
+
158
+ [mit license](LICENSE)