codexport 0.1.1 → 0.1.3

package/README.md

@@ -8,9 +8,9 @@
 
 ---
 
-`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.
+`codexport` replicates a canonical master 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.
 
-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.
+the master 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.
 
 [npm](https://www.npmjs.com/package/codexport) | [github](https://github.com/Microck/codexport)
 
@@ -18,7 +18,7 @@ Machine1 serves a content-hashed bundle from its `~/.codex` directory. followers
 
 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.
 
-- keep Machine1 as the canonical Codex configuration source
+- keep the master as the canonical Codex configuration source
 - let followers preserve local MCPs, local skills, trust entries, and path overrides
 - sync auth-bearing files through the private Tailscale path instead of a plaintext GitHub commit
 - refresh followers at Codex session startup without interrupting active sessions
@@ -28,18 +28,18 @@ if you keep a carefully tuned Codex setup on one machine and want the same defau
 
 `codexport` requires Node.js 20+.
 
-on Machine1:
+on the master:
 
 ```bash
 npx codexport master init
 npx codexport master service install
-npx codexport master link --host machine1.tailnet.ts.net
+npx codexport master link --host master.tailnet.ts.net
 ```
 
 on a follower:
 
 ```bash
-npx codexport follower join "codexport://join?host=machine1.tailnet.ts.net&port=17342&fingerprint=..."
+npx codexport follower join "codexport://join?host=master.tailnet.ts.net&port=17342&fingerprint=..."
 npx codexport hook install
 ```
 
@@ -52,16 +52,58 @@ npx codexport status
 
 ## sync model
 
-```text
-Machine1 ~/.codex
-  -> codexport master serve
-  -> Tailscale-reachable HTTP bundle
-  -> follower sync/apply
-  -> generated follower ~/.codex
+```mermaid
+flowchart LR
+  subgraph master["master machine"]
+    masterCodex["~/.codex canonical state"]
+    masterCli["codexport master serve"]
+    masterBundle["content-hashed bundle"]
+  end
+
+  subgraph privateNet["tailscale network"]
+    http["http://master.tailnet.ts.net:17342"]
+  end
+
+  subgraph follower["follower machine"]
+    localOverlay["~/.codexport local overlay"]
+    sessionHook["Codex SessionStart hook"]
+    generatedCodex["generated ~/.codex"]
+  end
+
+  masterCodex -->|select files and hash content| masterBundle
+  masterBundle --> masterCli
+  masterCli -->|serve bundle and fingerprint| http
+  sessionHook -->|check revision before session| http
+  http -->|download changed bundle| sessionHook
+  localOverlay -->|merge MCPs, skills, path variables| sessionHook
+  sessionHook -->|backup and apply| generatedCodex
 ```
 
 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.
 
+## trust flow
+
+```mermaid
+sequenceDiagram
+  participant Operator as operator
+  participant Master as master
+  participant Follower as follower
+  participant Codex as codex session
+
+  Operator->>Master: codexport master link
+  Master-->>Operator: join link with host, port, fingerprint
+  Operator->>Follower: codexport follower join "codexport://join?..."
+  Follower->>Master: GET /meta
+  Master-->>Follower: fingerprint and revision
+  Follower->>Follower: pin trusted fingerprint
+  Follower->>Master: GET /bundle
+  Master-->>Follower: content-hashed bundle
+  Follower->>Follower: apply bundle plus local overlay
+  Codex->>Follower: SessionStart hook
+  Follower->>Master: check revision and fingerprint
+  Follower-->>Codex: continue with latest applied config
+```
+
 ## included state
 
 the master bundle includes canonical Codex config, auth files, hooks, prompts,
@@ -100,7 +142,7 @@ the follower's `local.toml` before writing the generated `~/.codex/config.toml`.
 
 | command | purpose |
 | --- | --- |
-| `codexport master init` | create or refresh Machine1 master identity and bundle state |
+| `codexport master init` | create or refresh the master identity and bundle state |
 | `codexport master serve` | serve the current canonical bundle over HTTP |
 | `codexport master link` | print a durable follower join link and fallback command |
 | `codexport master rebuild` | force rebuild the master bundle for repair/debugging |
@@ -125,14 +167,14 @@ followers do not need a background service in v1. the hook runs a short best-eff
 generate a copy-paste join command:
 
 ```bash
-codexport master link --host machine1.tailnet.ts.net
+codexport master link --host master.tailnet.ts.net
 ```
 
 join with explicit trust metadata:
 
 ```bash
 codexport follower join \
-  --master http://machine1.tailnet.ts.net:17342 \
+  --master http://master.tailnet.ts.net:17342 \
   --fingerprint <fingerprint> \
   --apply
 ```

package/dist/index.js

@@ -3,7 +3,7 @@ import { Command, Option } from "commander";
 import chokidar from "chokidar";
 import { createHash, randomBytes } from "node:crypto";
 import { createServer, request } from "node:http";
-import { mkdir, readFile, readdir, readlink, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, readdir, readlink, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -11,7 +11,7 @@ import { homedir, platform } from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
-const VERSION = "0.1.1";
+const VERSION = "0.1.3";
 const DEFAULT_PORT = 17342;
 const DEFAULT_TIMEOUT_MS = 5_000;
 const CODEXPORT_DIR = ".codexport";
@@ -187,7 +187,10 @@ async function walkIncluded(root, absolute, files) {
     const relative = normalizeRelative(path.relative(root, absolute));
     if (!relative || shouldExclude(relative))
         return;
-    const entryStat = await stat(absolute);
+    const entryStat = await lstat(absolute);
+    if (entryStat.isSymbolicLink()) {
+        return;
+    }
     if (entryStat.isDirectory()) {
         const children = await readdir(absolute);
         for (const child of children) {
@@ -533,7 +536,7 @@ async function commandMasterLink(ctx, options) {
     const identity = await loadMasterIdentity(ctx);
     const local = await readLocalConfig(ctx);
     const port = options.port ?? local.port ?? DEFAULT_PORT;
-    const host = options.host ?? "machine1.tailnet.ts.net";
+    const host = options.host ?? "master.tailnet.ts.net";
     const url = masterUrl(host, port);
     print(ctx, {
         joinLink: buildJoinLink(url, identity.fingerprint),
@@ -674,7 +677,7 @@ async function main(argv) {
         .name("codexport")
         .description("Replicate a canonical Codex setup from a master machine to follower machines.")
         .version(VERSION);
-    const master = program.command("master").description("Manage the canonical Machine1 export.");
+    const master = program.command("master").description("Manage the canonical master export.");
     master.command("init")
         .description("Create or refresh master identity and canonical bundle state.")
         .option("--port <port>", "default serve port", parsePositiveInt, DEFAULT_PORT)
@@ -684,7 +687,7 @@ async function main(argv) {
         .action(async (_options, command) => commandMasterRebuild(contextFromCommand(command)));
     master.command("link")
         .description("Print a durable follower join link and copy-paste command.")
-        .option("--host <host>", "Tailscale host, IP, or full URL", "machine1.tailnet.ts.net")
+        .option("--host <host>", "Tailscale host, IP, or full URL", "master.tailnet.ts.net")
         .option("--port <port>", "master port", parsePositiveInt, DEFAULT_PORT)
         .action(async (options, command) => commandMasterLink(contextFromCommand(command), options));
     master.command("serve")
@@ -706,7 +709,7 @@ async function main(argv) {
     const follower = program.command("follower").description("Enroll and manage a follower machine.");
     follower.command("join [link]")
         .description("Enroll this follower from a codexport://join link or explicit master URL.")
-        .option("--master <url>", "master URL, for example http://machine1.tailnet.ts.net:17342")
+        .option("--master <url>", "master URL, for example http://master.tailnet.ts.net:17342")
         .option("--fingerprint <hex>", "expected master fingerprint")
         .option("--apply", "download and apply immediately after enrollment")
         .option("--timeout-ms <ms>", "network timeout", parsePositiveInt, DEFAULT_TIMEOUT_MS)

package/docs/prd.md

@@ -7,14 +7,14 @@ Status: implemented as an initial Node.js CLI in this repository.
 Build a low-friction way to replicate the useful parts of a master machine's
 Codex setup to follower machines.
 
-The main target is `~/.codex`. Machine1 is the source of truth. Follower
+The main target is `~/.codex`. The master is the source of truth. Follower
 machines should stay up to date automatically while still being allowed to keep
 machine-local additions such as local MCPs, local skills, local trust entries,
 and local path overrides.
 
 ## Product Principles
 
-- Machine1 owns the canonical Codex configuration.
+- The master owns the canonical Codex configuration.
 - Followers are read-only consumers of canonical state.
 - Followers can keep local-only overlays unless those overlays explicitly
   conflict with canonical names.
@@ -37,32 +37,32 @@ The project will live at:
 
 ### Authority Model
 
-Machine1 is canonical. Follower machines do not push changes back by default.
+The master is canonical. Follower machines do not push changes back by default.
 
 Follower-specific additions are allowed, but they remain local unless promoted
-from Machine1 intentionally.
+from the master intentionally.
 
 ### Sync Transport
 
 Use a Tailscale-compatible pull model:
 
 ```text
-Machine1:
+Master:
   codexport serve
 
 Follower:
   codexport join
-  > Master Tailscale IP/name: machine1.tailnet.ts.net
+  > Master Tailscale IP/name: master.tailnet.ts.net
 ```
 
-Followers pull from Machine1. Machine1 does not need to track and push to every
+Followers pull from the master. The master does not need to track and push to every
 follower.
 
 Tailscale reachability is sufficient for follower enrollment. The first version
 does not require a separate one-time pairing code.
 
-Machine1 should run the master server persistently as a user-level service.
-Followers should be able to reconnect and sync whenever Machine1 is online.
+The master should run the master server persistently as a user-level service.
+Followers should be able to reconnect and sync whenever the master is online.
 
 On first join, the follower trusts the provided Tailscale address and stores the
 master instance fingerprint. Later syncs must verify that fingerprint. If the
@@ -71,7 +71,7 @@ re-enroll or trust-reset command.
 
 ### One-Click Join
 
-Machine1 should be able to generate a durable join artifact for followers.
+The master should be able to generate a durable join artifact for followers.
 
 Preferred UX:
 
@@ -83,14 +83,14 @@ Outputs a permanent join link or command that a follower can run without
 manually typing the master address:
 
 ```text
-npx codexport follower join "codexport://join?host=machine1.tailnet.ts.net&port=17342&fingerprint=..."
+npx codexport follower join "codexport://join?host=master.tailnet.ts.net&port=17342&fingerprint=..."
 ```
 
 If custom URL handling is too complex for the first implementation, the
 fallback is a one-time copy-paste command:
 
 ```text
-npx codexport follower join --master http://machine1.tailnet.ts.net:17342 --fingerprint ...
+npx codexport follower join --master http://master.tailnet.ts.net:17342 --fingerprint ...
 ```
 
 The join link should not include plaintext Codex secrets. It should include only
@@ -128,9 +128,9 @@ Followers should sync automatically through a follower-only Codex `SessionStart`
 hook:
 
 - The hook runs a short best-effort sync before a new Codex session starts.
-- If Machine1 is reachable and the content hash changed, the follower applies
+- If the master is reachable and the content hash changed, the follower applies
   the update before the session continues.
-- If Machine1 is unavailable, the hook exits cleanly and Codex starts with the
+- If the master is unavailable, the hook exits cleanly and Codex starts with the
   most recently applied config.
 
 This means followers are guaranteed to refresh at the Codex session boundary,
@@ -142,7 +142,7 @@ available when an immediate refresh is needed outside session startup.
 The tool should generate the final `~/.codex/config.toml` from layers:
 
 ```text
-canonical config from Machine1
+canonical config from the master
 local follower overlay
 generated final ~/.codex/config.toml
 ```
@@ -213,7 +213,7 @@ The user wants auth and important state to sync for a one-click experience.
 
 The current design should not store plaintext secrets in GitHub. Instead:
 
-- Machine1 can include secret-bearing files in a private export bundle served
+- The master can include secret-bearing files in a private export bundle served
   over Tailscale.
 - Followers fetch and apply that bundle during `join` or automatic sync.
 - GitHub stores code and non-secret portable config, not plaintext token blobs.
@@ -265,7 +265,7 @@ Recommended package shape:
 - Optional later installer that writes the master service and follower hook.
 
 The tool may still install or configure Bun as part of the synced development
-toolchain if Machine1's `mise.toml` requests it.
+toolchain if the master's `mise.toml` requests it.
 
 The published package should require Node.js 20 or newer.
 
@@ -307,10 +307,10 @@ Rejected for v1:
 
 Expected roles:
 
-- `master init`: create Machine1 canonical state.
+- `master init`: create the master canonical state.
 - `master serve`: serve canonical bundle over Tailscale-reachable HTTP.
 - `master link`: print a durable follower join link or copy-paste command.
-- `follower join`: enroll a follower by asking for Machine1 Tailscale IP/name.
+- `follower join`: enroll a follower by asking for the master Tailscale IP/name.
 - `sync`: fetch and stage/apply updates.
 - `apply`: apply already available canonical state plus local overlays.
 - `hook install`: install follower-only Codex SessionStart sync hook.
@@ -352,7 +352,7 @@ Follower hook:
 - Downloads and validates new revisions when changed.
 - Verifies the stored master fingerprint before accepting an update.
 - Applies before the new Codex session proceeds.
-- Uses a short timeout so Codex startup is not blocked for long when Machine1 is
+- Uses a short timeout so Codex startup is not blocked for long when the master is
   offline.
 - Does not require a follower background service in v1.
 
@@ -405,7 +405,7 @@ Canonical names win by default. A same-name local MCP or skill fails unless
 12. Should master export rebuilds require a manual command or happen
     automatically? Decision: master watches selected paths and rebuilds
     automatically; manual rebuild exists only for repair/debugging.
-13. Should Machine1 generate a permanent follower join link or require manual
+13. Should the master generate a permanent follower join link or require manual
     master address entry? Decision: generate a durable join link, with a
     copy-paste command fallback if custom URL handling is not implemented in the
     first version.
@@ -428,7 +428,7 @@ Canonical names win by default. A same-name local MCP or skill fails unless
 
 - macOS support.
 - GitHub-based plaintext secret sync.
-- Push-based orchestration from Machine1 to followers.
+- Push-based orchestration from the master to followers.
 - Mid-session mutation of active Codex behavior.
 - Automatic promotion of follower-local changes.
 - Syncing Codex sessions, history, logs, or SQLite runtime state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexport",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "sync a canonical Codex setup from one master machine to follower machines",
   "author": "Microck <contact@micr.dev>",
   "license": "MIT",