csession 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamie Steiner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# csession
+
+Move a Claude Code session from one machine to another — or hand one to a peer
+so they can pick up the work.
+
+A session is a JSONL transcript that lives only on the machine that made it.
+Copying the file is not enough: it is full of that machine's absolute paths, it
+assumes a specific git commit, and it contains every secret ever printed into
+it. `csession` packages a session into one file that survives the trip.
+
+```
+csession export [id] -o work.ccsession    # redacts secrets, records git state
+csession inspect work.ccsession           # look before you send
+csession import work.ccsession            # rewrites paths, refuses to guess
+```
+
+Status: **phase 1 implemented.** `list`, `export`, `inspect` and `import` work.
+Deferred: `csession send <host>`, a2a drop-board publishing, and a slash-command wrapper.
+
+```bash
+npm install && npm test    # build and run the suite
+node dist/cli.js --help
+```
+
+Design: [docs/superpowers/specs/2026-08-31-csession-design.md](docs/superpowers/specs/2026-08-31-csession-design.md)

package/dist/args.js

@@ -0,0 +1,50 @@
+import { run } from "./git.js";
+const SHORT = { o: "out" };
+export function parseArgs(argv) {
+    if (argv.length === 0)
+        return { command: "help", positional: [], flags: {} };
+    const [command, ...rest] = argv;
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const tok = rest[i];
+        if (tok.startsWith("--")) {
+            const body = tok.slice(2);
+            const eq = body.indexOf("=");
+            if (eq !== -1) {
+                flags[body.slice(0, eq)] = body.slice(eq + 1);
+            }
+            else {
+                const next = rest[i + 1];
+                if (next !== undefined && !next.startsWith("-")) {
+                    flags[body] = next;
+                    i++;
+                }
+                else {
+                    flags[body] = true;
+                }
+            }
+        }
+        else if (tok.startsWith("-") && tok.length === 2) {
+            const name = SHORT[tok.slice(1)] ?? tok.slice(1);
+            const next = rest[i + 1];
+            if (next !== undefined && !next.startsWith("-")) {
+                flags[name] = next;
+                i++;
+            }
+            else {
+                flags[name] = true;
+            }
+        }
+        else {
+            positional.push(tok);
+        }
+    }
+    return { command: command, positional, flags };
+}
+/** The git root of `cwd`, or `cwd` itself when it is not in a repo. */
+export function resolveProjectRoot(cwd) {
+    const r = run(cwd, ["rev-parse", "--show-toplevel"]);
+    return r.ok && r.stdout ? r.stdout : cwd;
+}
+//# sourceMappingURL=args.js.map

package/dist/bundle.js

@@ -0,0 +1,73 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, basename } from "node:path";
+import { CorruptBundleError } from "./errors.js";
+/** Write via a sibling temp file then rename, so a failure never leaves a partial artefact. */
+export function atomicWrite(dest, data) {
+    const dir = dirname(dest);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.${basename(dest)}.${process.pid}.tmp`);
+    try {
+        writeFileSync(tmp, data);
+        renameSync(tmp, dest);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw e;
+    }
+}
+/** A gzipped tar of exactly the named files, flat, no directory entries. */
+export function writeBundle(outPath, files) {
+    const staging = mkdtempSync(join(tmpdir(), "csession-stage-"));
+    try {
+        for (const [name, content] of Object.entries(files)) {
+            writeFileSync(join(staging, name), content);
+        }
+        const tarOut = join(staging, ".bundle.tgz");
+        const names = Object.keys(files);
+        const r = spawnSync("tar", ["-czf", tarOut, "-C", staging, ...names], { encoding: "utf8" });
+        if (r.status !== 0) {
+            throw new Error(`tar failed: ${r.stderr ?? ""}`);
+        }
+        atomicWrite(outPath, readFileSync(tarOut));
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+export function readBundle(bundlePath) {
+    const staging = mkdtempSync(join(tmpdir(), "csession-unstage-"));
+    try {
+        const r = spawnSync("tar", ["-xzf", bundlePath, "-C", staging], { encoding: "utf8" });
+        if (r.status !== 0) {
+            throw new CorruptBundleError(`not a readable .ccsession bundle: ${(r.stderr ?? "").trim()}`);
+        }
+        const out = {};
+        // Bundles are untrusted input from another machine. Every malformed shape must become
+        // a typed refusal (exit code 3) rather than a crash that touches the filesystem unexpectedly.
+        const entries = readdirSync(staging, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile()) {
+                throw new CorruptBundleError(`bundle contains a non-regular entry: "${entry.name}" (not a regular file)`);
+            }
+            try {
+                out[entry.name] = readFileSync(join(staging, entry.name), "utf8");
+            }
+            catch (e) {
+                throw new CorruptBundleError(`failed to read "${entry.name}" from bundle: ${e.message}`);
+            }
+        }
+        if (!("manifest.json" in out)) {
+            throw new CorruptBundleError("bundle contains no manifest.json");
+        }
+        if (!("session.jsonl" in out)) {
+            throw new CorruptBundleError("bundle contains no session.jsonl");
+        }
+        return out;
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=bundle.js.map

package/dist/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { parseArgs } from "./args.js";
+import { CsError } from "./errors.js";
+import { listCommand } from "./commands/list.js";
+import { exportCommand } from "./commands/export.js";
+import { inspectCommand } from "./commands/inspect.js";
+import { importCommand } from "./commands/import.js";
+const HELP = `csession - move a Claude Code session between machines
+
+  csession list [--project PATH]              sessions for a project, newest first
+  csession export [id] -o FILE [options]      build a bundle
+  csession inspect FILE                       print manifest and reports
+  csession import FILE [options]              receive a bundle
+
+export options:  --dry-run  --include-untracked  --paranoid  --no-redact
+import options:  --root PATH  --new-id  --force
+
+exit codes: 0 ok, 1 user error, 2 safety refusal, 3 corrupt bundle`;
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    switch (args.command) {
+        case "list":
+            console.log(listCommand(args.flags, process.cwd()));
+            return 0;
+        case "export":
+            console.log(exportCommand(args.positional, args.flags, process.cwd(), new Date()));
+            return 0;
+        case "inspect":
+            console.log(inspectCommand(args.positional));
+            return 0;
+        case "import":
+            console.log(importCommand(args.positional, args.flags, process.cwd()));
+            return 0;
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(HELP);
+            return 0;
+        default:
+            console.error(`unknown command: ${args.command}\n\n${HELP}`);
+            return 1;
+    }
+}
+try {
+    process.exit(main());
+}
+catch (e) {
+    if (e instanceof CsError) {
+        console.error(`error: ${e.message}`);
+        process.exit(e.exitCode);
+    }
+    else {
+        // An untyped error is still a user-facing failure, and a stack trace is never the
+        // right thing to show someone for one. transcript.ts, git.ts and bundle.ts all throw
+        // plain Errors - several are genuine programmer-error guards that must stay loud in
+        // tests, so they are not being converted; this net is what keeps them from reaching
+        // a person as a wall of Node internals. Exit 1: an untyped failure is not a safety
+        // refusal (2) and not a diagnosed corrupt bundle (3).
+        console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/commands/export.js

@@ -0,0 +1,113 @@
+import { readFileSync } from "node:fs";
+import { listSessionFiles, sessionFilePath } from "../paths.js";
+import { readLines, statTranscript, deriveProjectRoot, sha256 } from "../transcript.js";
+import { redact } from "../redact.js";
+import { probe, diffPatch, untrackedPatch } from "../git.js";
+import { writeBundle } from "../bundle.js";
+import { SCHEMA } from "../manifest.js";
+import { UserError } from "../errors.js";
+import { resolveProjectRoot } from "../args.js";
+export function exportCommand(positional, flags, cwd, now) {
+    const out = flags["out"];
+    const dryRun = flags["dry-run"] === true;
+    if (typeof out !== "string" && !dryRun) {
+        throw new UserError("export needs an output path: csession export [id] -o FILE");
+    }
+    const projectRoot = resolveProjectRoot(cwd);
+    const available = listSessionFiles(projectRoot);
+    if (available.length === 0) {
+        throw new UserError(`no sessions found for ${projectRoot}`);
+    }
+    const requested = positional[0];
+    const chosen = requested
+        ? available.find((s) => s.id === requested)
+        : available[0];
+    if (!chosen) {
+        throw new UserError(`no session "${requested}" for ${projectRoot}. Run: csession list`);
+    }
+    const raw = readFileSync(sessionFilePath(projectRoot, chosen.id), "utf8");
+    const originalLines = readLines(raw);
+    const stats = statTranscript(originalLines);
+    const derived = deriveProjectRoot(stats);
+    const notes = [];
+    if (!requested)
+        notes.push(`No id given; chose the newest session ${chosen.id}.`);
+    if (derived.ambiguous) {
+        notes.push(`Records disagree on cwd; using the most common: ${derived.root}`);
+    }
+    const applyRedaction = flags["no-redact"] !== true;
+    const paranoid = flags["paranoid"] === true;
+    const { lines, hits } = applyRedaction
+        ? redact(originalLines, { paranoid })
+        : { lines: originalLines, hits: [] };
+    const sessionJsonl = lines.join("\n") + "\n";
+    const git = probe(derived.root);
+    const includeUntracked = flags["include-untracked"] === true;
+    let patch = git.dirty || includeUntracked ? diffPatch(derived.root) : "";
+    if (includeUntracked) {
+        patch += untrackedPatch(derived.root, git.untrackedFiles);
+    }
+    const manifest = {
+        schema: SCHEMA,
+        createdAt: now.toISOString(),
+        session: {
+            id: chosen.id,
+            projectRoot: derived.root,
+            recordCount: lines.length,
+            sha256: sha256(sessionJsonl),
+            claudeVersions: stats.versions,
+        },
+        git: {
+            remote: git.remote,
+            branch: git.branch,
+            commit: git.commit,
+            dirty: git.dirty,
+            untrackedFiles: git.untrackedFiles,
+            includedUntracked: includeUntracked,
+        },
+        redaction: { applied: applyRedaction, paranoid, hits },
+    };
+    const report = buildReport(manifest, patch, notes, dryRun, includeUntracked);
+    if (dryRun)
+        return report;
+    const files = {
+        "manifest.json": JSON.stringify(manifest, null, 2) + "\n",
+        "session.jsonl": sessionJsonl,
+    };
+    if (patch.trim().length > 0)
+        files["uncommitted.patch"] = patch;
+    writeBundle(out, files);
+    return `${report}\n\nWrote ${out}`;
+}
+function buildReport(m, patch, notes, dryRun, includeUntracked) {
+    const l = [];
+    if (dryRun)
+        l.push("DRY RUN - nothing was written.");
+    l.push(...notes);
+    l.push(`session   ${m.session.id}  (${m.session.recordCount} records)`);
+    l.push(`root      ${m.session.projectRoot}`);
+    l.push(`git       ${m.git.branch ?? "?"} @ ${(m.git.commit ?? "?").slice(0, 12)}  dirty=${m.git.dirty}`);
+    if (patch.trim().length > 0) {
+        const kb = Math.round(Buffer.byteLength(patch) / 1024);
+        l.push(`patch     ${kb}K`);
+        if (kb > 1024)
+            l.push(`WARNING: the patch is ${kb}K. Consider committing first.`);
+    }
+    if (m.git.untrackedFiles.length > 0) {
+        const verb = includeUntracked ? "included" : "NOT included";
+        l.push(`untracked ${m.git.untrackedFiles.length} file(s) ${verb}: ${m.git.untrackedFiles.join(", ")}`);
+    }
+    if (m.redaction.applied) {
+        l.push(m.redaction.hits.length === 0
+            ? "redaction no matches"
+            : `redaction ${m.redaction.hits.map((h) => `${h.rule}x${h.count}`).join(", ")}`);
+    }
+    else {
+        l.push("redaction DISABLED (--no-redact). This bundle may contain secrets.");
+    }
+    l.push("");
+    l.push("Redaction is best-effort. A secret that is split across lines, encoded,");
+    l.push("or oddly shaped can still get through. Inspect before you send.");
+    return l.join("\n");
+}
+//# sourceMappingURL=export.js.map

package/dist/commands/import.js

@@ -0,0 +1,147 @@
+import { randomUUID } from "node:crypto";
+import { writeFileSync, mkdtempSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { readBundle, atomicWrite } from "../bundle.js";
+import { parseManifest } from "../manifest.js";
+import { readLines, rewritePrefix, replaceAllText, unresolvedAbsolutePaths, sha256 } from "../transcript.js";
+import { probe, applyCheck } from "../git.js";
+import { sessionFilePath } from "../paths.js";
+import { resolveProjectRoot } from "../args.js";
+import { UserError, SafetyError, CorruptBundleError } from "../errors.js";
+import { safe } from "../sanitize.js";
+import { existsSync } from "node:fs";
+/**
+ * Claude Code session ids are UUIDs. Anything else is a malformed bundle.
+ *
+ * This is a hard gate rather than a nicety because the id is attacker-controlled and
+ * gets used in two dangerous places: sessionFilePath() interpolates it into a
+ * filesystem path (an id of "../../../../tmp/pwned" escapes the sessions folder
+ * entirely, and atomicWrite's recursive mkdir happily creates the way there, with the
+ * equally attacker-controlled transcript as the content), and buildReport prints it
+ * inside a `claude --resume <id>` command we invite the reader to run.
+ */
+const SESSION_ID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+export function importCommand(positional, flags, cwd) {
+    const path = positional[0];
+    if (!path)
+        throw new UserError("import needs a bundle path: csession import FILE");
+    const files = readBundle(path);
+    const m = parseManifest(files["manifest.json"]);
+    // Before the id is used for ANYTHING - see SESSION_ID_RE above.
+    if (!SESSION_ID_RE.test(m.session.id)) {
+        throw new CorruptBundleError(`manifest session id is not a UUID: "${safe(m.session.id, 80)}". ` +
+            `That string would become a file path and a command to run; refusing.`);
+    }
+    const sessionJsonl = files["session.jsonl"];
+    const actual = sha256(sessionJsonl);
+    if (actual !== m.session.sha256) {
+        throw new CorruptBundleError(`transcript checksum does not match the manifest (expected ${m.session.sha256}, got ${actual})`);
+    }
+    const root = resolveLocalRoot(flags, cwd, m.git.remote);
+    const force = flags["force"] === true;
+    const local = probe(root);
+    // Every `m.*` below is a manifest string - see sanitize.ts. `local.*` and `root` are
+    // ours: read from the receiver's own repo, or validated here.
+    if (m.git.remote && local.remote && m.git.remote !== local.remote && !force) {
+        throw new SafetyError(`remote mismatch.\n  bundle: ${safe(m.git.remote)}\n  local:  ${local.remote}\n` +
+            `This may be a different repository. Re-run with --force if you are sure.`);
+    }
+    if (m.git.commit && local.commit && m.git.commit !== local.commit && !force) {
+        throw new SafetyError(`commit mismatch.\n  bundle: ${safe(m.git.commit)}\n  local:  ${local.commit}\n\n` +
+            `The conversation assumes the bundle's tree. To match it:\n` +
+            `  git -C ${root} checkout ${safe(m.git.commit)}\n\n` +
+            `Or re-run with --force to import anyway.`);
+    }
+    const newId = flags["new-id"] === true ? randomUUID() : m.session.id;
+    const dest = sessionFilePath(root, newId);
+    if (existsSync(dest)) {
+        throw new SafetyError(`session ${newId} already exists at ${dest}. Re-run with --new-id to import it under a fresh id.`);
+    }
+    let lines = readLines(sessionJsonl);
+    const rewritten = rewritePrefix(lines, m.session.projectRoot, root);
+    lines = rewritten.lines;
+    if (newId !== m.session.id) {
+        lines = replaceAllText(lines, m.session.id, newId).lines;
+    }
+    const unresolved = unresolvedAbsolutePaths(lines, root);
+    atomicWrite(dest, lines.join("\n") + "\n");
+    return buildReport(m, root, newId, rewritten.replaced, unresolved, files, force);
+}
+function resolveLocalRoot(flags, cwd, bundleRemote) {
+    const explicit = flags["root"];
+    if (typeof explicit === "string") {
+        // A relative or non-existent --root is worse than an error: probe() returns all
+        // nulls for it, so every safety check below passes VACUOUSLY, the transcript lands
+        // in a folder Claude Code will never read, and we report success with a resume
+        // command that cannot work. Resolve it too - the value ends up in a session folder
+        // name and in that printed command, both of which must be absolute.
+        const abs = resolve(explicit);
+        let isDir = false;
+        try {
+            isDir = statSync(abs).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir) {
+            throw new UserError(`--root ${explicit} is not an existing directory (resolved to ${abs})`);
+        }
+        return abs;
+    }
+    const here = resolveProjectRoot(cwd);
+    const local = probe(here);
+    if (bundleRemote && local.remote === bundleRemote)
+        return here;
+    throw new UserError(`cannot work out where this repository lives here.\n` +
+        `  bundle remote: ${bundleRemote === null ? "none recorded" : safe(bundleRemote)}\n` +
+        `  current dir:   ${here} (remote: ${local.remote ?? "none"})\n\n` +
+        `Re-run from inside the right checkout, or pass --root PATH.`);
+}
+function buildReport(m, root, newId, replaced, unresolved, files, force) {
+    const l = [];
+    l.push(`session ${newId}  (${m.session.recordCount} records)`);
+    if (newId !== m.session.id)
+        l.push(`  (original id was ${safe(m.session.id)})`);
+    l.push(`${replaced} paths rewritten to ${root}`);
+    if (unresolved.length > 0) {
+        l.push(`${unresolved.length} path(s) left as-is (not under the project root):`);
+        for (const p of unresolved.slice(0, 20))
+            l.push(`  ${p}`);
+        if (unresolved.length > 20)
+            l.push(`  ... and ${unresolved.length - 20} more`);
+    }
+    if (m.git.untrackedFiles.length > 0) {
+        const n = m.git.untrackedFiles.length;
+        // Saying "not in the bundle" unconditionally was wrong whenever the sender used
+        // --include-untracked: the contents are right there in uncommitted.patch.
+        l.push(m.git.includedUntracked
+            ? `NOTE: ${n} untracked file(s) referenced by this session ARE included in this bundle, in uncommitted.patch:`
+            : `NOTE: ${n} untracked file(s) referenced by this session are NOT included in this bundle:`);
+        for (const f of m.git.untrackedFiles)
+            l.push(`  ${safe(f)}`);
+    }
+    const patch = files["uncommitted.patch"];
+    if (patch) {
+        // A predictable path in the shared /tmp namespace (e.g. csession-<id>.patch) lets
+        // anyone who has seen the bundle pre-plant a symlink there for writeFileSync to
+        // follow. mkdtempSync makes a private, unpredictable directory first.
+        const patchDir = mkdtempSync(join(tmpdir(), "csession-patch-"));
+        const patchPath = join(patchDir, `csession-${newId}.patch`);
+        writeFileSync(patchPath, patch);
+        const check = applyCheck(root, patchPath);
+        l.push("");
+        l.push(`This session had uncommitted changes. They were NOT applied.`);
+        l.push(`  patch (temporary file): ${patchPath}`);
+        l.push(`  applies:    ${check.ok ? "cleanly" : `NO - ${check.output}`}`);
+        l.push(`  to apply:   git -C ${root} apply ${patchPath}`);
+    }
+    if (force) {
+        l.push("");
+        l.push("WARNING: --force was used. The history may describe a tree you do not have.");
+    }
+    l.push("");
+    l.push(`Resume with:  cd ${root} && claude --resume ${newId}`);
+    return l.join("\n");
+}
+//# sourceMappingURL=import.js.map

package/dist/commands/inspect.js

@@ -0,0 +1,35 @@
+import { readBundle } from "../bundle.js";
+import { parseManifest } from "../manifest.js";
+import { sha256 } from "../transcript.js";
+import { UserError } from "../errors.js";
+import { safe } from "../sanitize.js";
+export function inspectCommand(positional) {
+    const path = positional[0];
+    if (!path)
+        throw new UserError("inspect needs a bundle path: csession inspect FILE");
+    const files = readBundle(path);
+    const m = parseManifest(files["manifest.json"]);
+    const actual = sha256(files["session.jsonl"]);
+    const shaLine = actual === m.session.sha256 ? "sha256 OK" : `sha256 MISMATCH (expected ${m.session.sha256}, got ${actual})`;
+    const l = [];
+    l.push(`bundle    ${path}`);
+    l.push(`created   ${m.createdAt}`);
+    l.push(`session   ${safe(m.session.id)}  (${m.session.recordCount} records)`);
+    l.push(`root      ${safe(m.session.projectRoot)}`);
+    l.push(`versions  ${m.session.claudeVersions.map((v) => safe(v)).join(", ") || "unknown"}`);
+    l.push(`git       ${safe(m.git.branch ?? "?")} @ ${safe((m.git.commit ?? "?").slice(0, 12))}  dirty=${m.git.dirty}`);
+    l.push(`remote    ${safe(m.git.remote ?? "none")}`);
+    l.push(`patch     ${"uncommitted.patch" in files ? `${Math.round(Buffer.byteLength(files["uncommitted.patch"]) / 1024)}K` : "none"}`);
+    if (m.git.untrackedFiles.length > 0) {
+        // Whether the contents actually shipped is recorded by export; saying "not in this
+        // bundle" unconditionally was a lie half the time.
+        const where = m.git.includedUntracked ? "included in this bundle" : "NOT included in this bundle";
+        l.push(`untracked ${where}: ${m.git.untrackedFiles.map((f) => safe(f)).join(", ")}`);
+    }
+    l.push(m.redaction.applied
+        ? `redaction ${m.redaction.hits.map((h) => `${safe(h.rule)}x${h.count}`).join(", ") || "no matches"}${m.redaction.paranoid ? " (paranoid)" : ""}`
+        : "redaction DISABLED - this bundle may contain secrets");
+    l.push(shaLine);
+    return l.join("\n");
+}
+//# sourceMappingURL=inspect.js.map

package/dist/commands/list.js

@@ -0,0 +1,17 @@
+import { listSessionFiles } from "../paths.js";
+import { resolveProjectRoot } from "../args.js";
+export function listCommand(flags, cwd) {
+    const explicit = typeof flags["project"] === "string" ? flags["project"] : undefined;
+    const root = explicit ?? resolveProjectRoot(cwd);
+    const sessions = listSessionFiles(root);
+    if (sessions.length === 0) {
+        return `No sessions found for ${root}`;
+    }
+    const rows = sessions.map((s) => {
+        const when = new Date(s.mtimeMs).toISOString().replace("T", " ").slice(0, 16);
+        const kb = `${Math.round(s.bytes / 1024)}K`.padStart(7);
+        return `  ${s.id}  ${when}  ${kb}`;
+    });
+    return [`Sessions for ${root} (newest first):`, ...rows].join("\n");
+}
+//# sourceMappingURL=list.js.map

package/dist/errors.js

@@ -0,0 +1,27 @@
+export class CsError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = new.target.name;
+    }
+}
+/** Bad arguments, missing file, unresolvable root. */
+export class UserError extends CsError {
+    constructor(message) {
+        super(message, 1);
+    }
+}
+/** A refusal: commit mismatch, remote mismatch, id collision. */
+export class SafetyError extends CsError {
+    constructor(message) {
+        super(message, 2);
+    }
+}
+/** Bad sha, unreadable manifest, unknown schema. */
+export class CorruptBundleError extends CsError {
+    constructor(message) {
+        super(message, 3);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/git.js

@@ -0,0 +1,68 @@
+import { spawnSync } from "node:child_process";
+export function run(root, args) {
+    const r = spawnSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 512 * 1024 * 1024 });
+    return {
+        ok: r.status === 0,
+        stdout: (r.stdout ?? "").trimEnd(),
+        stderr: (r.stderr ?? "").trimEnd(),
+    };
+}
+export function probe(root) {
+    if (!run(root, ["rev-parse", "--is-inside-work-tree"]).ok) {
+        return { remote: null, branch: null, commit: null, dirty: false, untrackedFiles: [] };
+    }
+    const remote = run(root, ["remote", "get-url", "origin"]);
+    const branch = run(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    const commit = run(root, ["rev-parse", "HEAD"]);
+    // --quiet exits non-zero when there is a tracked change. Untracked and
+    // ignored files do not affect it, which is exactly what we want.
+    const dirty = !run(root, ["diff", "--quiet", "HEAD"]).ok;
+    // --exclude-standard honours .gitignore, so ignored files never appear.
+    const untracked = run(root, ["ls-files", "--others", "--exclude-standard"]);
+    return {
+        remote: remote.ok ? remote.stdout : null,
+        branch: branch.ok ? branch.stdout : null,
+        commit: commit.ok ? commit.stdout : null,
+        dirty,
+        untrackedFiles: untracked.ok && untracked.stdout ? untracked.stdout.split("\n") : [],
+    };
+}
+/** Every change to a file git already knows about. Binary-safe so it applies cleanly. */
+export function diffPatch(root) {
+    const r = run(root, ["diff", "--binary", "HEAD"]);
+    // A failed diff is not "no changes" — conflating them yields a bundle that
+    // claims dirty with no patch. Throw loudly instead of silently returning "".
+    if (!r.ok) {
+        throw new Error(`git diff failed in ${root}: ${r.stderr || "(no stderr)"}`);
+    }
+    return r.stdout + "\n";
+}
+/**
+ * A patch for untracked, non-ignored files, built WITHOUT touching the index.
+ *
+ * `git diff HEAD` cannot see untracked files at all, so --include-untracked would
+ * otherwise be a no-op. `git add -N` would work but mutates the user's index as a
+ * side effect of an export, which an export must never do. `--no-index` against
+ * /dev/null gives the same hunks with no state change.
+ *
+ * The file list comes from probe().untrackedFiles, i.e. `ls-files --others
+ * --exclude-standard`, so anything matched by .gitignore is already excluded and
+ * stays excluded. This flag must never become --include-secrets.
+ */
+export function untrackedPatch(root, files) {
+    let out = "";
+    for (const file of files) {
+        // --no-index exits 1 when the inputs differ, which is always true here.
+        const r = spawnSync("git", ["diff", "--no-index", "--binary", "--", "/dev/null", file], { cwd: root, encoding: "utf8", maxBuffer: 512 * 1024 * 1024 });
+        if (r.status !== 0 && r.status !== 1) {
+            throw new Error(`git diff --no-index failed for ${file}: ${r.stderr ?? ""}`);
+        }
+        out += r.stdout ?? "";
+    }
+    return out;
+}
+export function applyCheck(root, patchPath) {
+    const r = run(root, ["apply", "--check", patchPath]);
+    return { ok: r.ok, output: r.stderr || r.stdout };
+}
+//# sourceMappingURL=git.js.map

package/dist/manifest.js

@@ -0,0 +1,91 @@
+import { CorruptBundleError } from "./errors.js";
+export const SCHEMA = 1;
+function req(obj, key, kind, path) {
+    const v = obj[key];
+    const actual = v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+    const want = kind === "array" ? "array" : kind;
+    const ok = kind === "array" ? Array.isArray(v) : kind === "nullable-string" ? v === null || typeof v === "string" : actual === want;
+    if (!ok)
+        throw new CorruptBundleError(`manifest: ${path}.${key} must be ${kind}, got ${actual}`);
+    return v;
+}
+/**
+ * `Array.isArray` says nothing about what is IN the array. Every consumer of these
+ * arrays treats the elements as strings - inspect maps them through safe(), which calls
+ * `.replace()` - so a non-string element becomes a TypeError with no exitCode: a
+ * stack trace and exit 1, when the contract says a malformed bundle is exit 3.
+ */
+function stringArray(o, key, path) {
+    const arr = req(o, key, "array", path);
+    arr.forEach((v, i) => {
+        if (typeof v !== "string") {
+            const actual = v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+            throw new CorruptBundleError(`manifest: ${path}.${key}[${i}] must be string, got ${actual}`);
+        }
+    });
+    return arr;
+}
+function obj(v, path) {
+    if (!v || typeof v !== "object" || Array.isArray(v)) {
+        throw new CorruptBundleError(`manifest: ${path} must be an object`);
+    }
+    return v;
+}
+export function parseManifest(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new CorruptBundleError("manifest.json is not valid JSON");
+    }
+    const m = obj(raw, "manifest");
+    const schema = req(m, "schema", "number", "manifest");
+    if (schema !== SCHEMA) {
+        throw new CorruptBundleError(`bundle uses schema ${schema}; this csession understands schema ${SCHEMA}. Upgrade csession.`);
+    }
+    const s = obj(req(m, "session", "object", "manifest"), "manifest.session");
+    const g = obj(req(m, "git", "object", "manifest"), "manifest.git");
+    const r = obj(req(m, "redaction", "object", "manifest"), "manifest.redaction");
+    const hits = req(r, "hits", "array", "manifest.redaction").map((h, i) => {
+        const hit = obj(h, `manifest.redaction.hits[${i}]`);
+        const extra = Object.keys(hit).filter((k) => k !== "rule" && k !== "count");
+        if (extra.length > 0) {
+            throw new CorruptBundleError(`manifest.redaction.hits[${i}] has unexpected field(s): ${extra.join(", ")}. Hits carry counts only.`);
+        }
+        return {
+            rule: req(hit, "rule", "string", `manifest.redaction.hits[${i}]`),
+            count: req(hit, "count", "number", `manifest.redaction.hits[${i}]`),
+        };
+    });
+    return {
+        schema,
+        createdAt: req(m, "createdAt", "string", "manifest"),
+        session: {
+            id: req(s, "id", "string", "manifest.session"),
+            projectRoot: req(s, "projectRoot", "string", "manifest.session"),
+            recordCount: req(s, "recordCount", "number", "manifest.session"),
+            sha256: req(s, "sha256", "string", "manifest.session"),
+            claudeVersions: stringArray(s, "claudeVersions", "manifest.session"),
+        },
+        git: {
+            remote: req(g, "remote", "nullable-string", "manifest.git"),
+            branch: req(g, "branch", "nullable-string", "manifest.git"),
+            commit: req(g, "commit", "nullable-string", "manifest.git"),
+            dirty: req(g, "dirty", "boolean", "manifest.git"),
+            untrackedFiles: stringArray(g, "untrackedFiles", "manifest.git"),
+            // Absent in bundles written before this field existed, so it defaults rather than
+            // failing - schema 1 stays schema 1. False is the conservative default: unless the
+            // bundle says the contents shipped, both readers tell the receiver they did not.
+            includedUntracked: g["includedUntracked"] === undefined
+                ? false
+                : req(g, "includedUntracked", "boolean", "manifest.git"),
+        },
+        redaction: {
+            applied: req(r, "applied", "boolean", "manifest.redaction"),
+            paranoid: req(r, "paranoid", "boolean", "manifest.redaction"),
+            hits,
+        },
+    };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/paths.js

@@ -0,0 +1,42 @@
+import { homedir } from "node:os";
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Claude Code names a project folder by taking the working directory and
+ * replacing every "/" with "-". This is lossy: "/a/b-c" and "/a/b/c" both
+ * encode to "-a-b-c". Encoding is safe; decoding is not, which is why the
+ * project root is derived from the transcript instead.
+ */
+export function encodeProjectDir(root) {
+    const trimmed = root.endsWith("/") && root.length > 1 ? root.slice(0, -1) : root;
+    return trimmed.replaceAll("/", "-");
+}
+export function claudeProjectsDir() {
+    return join(homedir(), ".claude", "projects");
+}
+export function sessionDirFor(root) {
+    return join(claudeProjectsDir(), encodeProjectDir(root));
+}
+export function sessionFilePath(root, sessionId) {
+    return join(sessionDirFor(root), `${sessionId}.jsonl`);
+}
+/** Sessions for a project root, newest first. Returns [] if the folder is absent. */
+export function listSessionFiles(root) {
+    const dir = sessionDirFor(root);
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((n) => n.endsWith(".jsonl"))
+        .map((n) => {
+        const path = join(dir, n);
+        const st = statSync(path);
+        return { id: n.slice(0, -".jsonl".length), path, mtimeMs: st.mtimeMs, bytes: st.size };
+    })
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+//# sourceMappingURL=paths.js.map

package/dist/redact.js

@@ -0,0 +1,54 @@
+const RULES = [
+    // Only exclude `"`, not `\`. PEM bodies inside JSON strings contain `\n` escapes;
+    // excluding backslash would stop the rule matching real keys inside strings.
+    // Quotes alone bound the JSON string, which is the property we need.
+    { name: "private-key", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[^"]*?-----END [A-Z ]*PRIVATE KEY-----/g },
+    { name: "anthropic-key", pattern: /sk-ant-[A-Za-z0-9_\-]{20,}/g },
+    { name: "tavily-key", pattern: /tvly-[A-Za-z0-9_\-]{20,}/g },
+    { name: "openai-key", pattern: /sk-(?:proj-)?[A-Za-z0-9]{32,}/g },
+    { name: "github-token", pattern: /gh[pousr]_[A-Za-z0-9]{30,}/g },
+    { name: "aws-access-key-id", pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+    { name: "google-api-key", pattern: /\bAIza[0-9A-Za-z_\-]{35}\b/g },
+    { name: "slack-token", pattern: /\bxox[baprs]-[0-9A-Za-z\-]{10,}/g },
+    { name: "stripe-key", pattern: /\b[sr]k_live_[0-9A-Za-z]{16,}/g },
+    // Only the password group is replaced, so the host stays readable.
+    { name: "connection-string-password", pattern: /([a-z][a-z0-9+.\-]*:\/\/[^\s:@"\\]+:)([^\s@"\\]+)(@)/g, group: 2 },
+    { name: "named-secret", pattern: /((?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|PWD)[A-Z_]*\s*[=:]\s*)([A-Za-z0-9_\-+/.]{16,})/g, group: 2 },
+];
+const PARANOID = [
+    { name: "high-entropy", pattern: /\b[A-Za-z0-9+/_\-]{40,}\b/g },
+];
+function isLowEntropy(s) {
+    // Hex-only strings are almost always commit SHAs or checksums, not secrets.
+    return /^[0-9a-f]+$/i.test(s);
+}
+export function redact(lines, opts) {
+    const rules = opts.paranoid ? [...RULES, ...PARANOID] : RULES;
+    const counts = new Map();
+    const out = lines.map((line) => {
+        let current = line;
+        for (const rule of rules) {
+            const re = new RegExp(rule.pattern.source, rule.pattern.flags);
+            current = current.replace(re, (...args) => {
+                const groups = args.slice(0, -2);
+                const whole = groups[0];
+                if (rule.name === "high-entropy" && isLowEntropy(whole))
+                    return whole;
+                counts.set(rule.name, (counts.get(rule.name) ?? 0) + 1);
+                const token = `[REDACTED:${rule.name}]`;
+                if (rule.group === undefined)
+                    return token;
+                return groups
+                    .slice(1)
+                    .map((g, i) => (i + 1 === rule.group ? token : (g ?? "")))
+                    .join("");
+            });
+        }
+        return current;
+    });
+    const hits = [...counts.entries()]
+        .map(([rule, count]) => ({ rule, count }))
+        .sort((a, b) => a.rule.localeCompare(b.rule));
+    return { lines: out, hits };
+}
+//# sourceMappingURL=redact.js.map

package/dist/sanitize.js

@@ -0,0 +1,24 @@
+/**
+ * Manifest strings come from whoever built the bundle. parseManifest checks their
+ * TYPE, never their CONTENT. Printed raw, an embedded ANSI or control sequence can
+ * visually overwrite earlier lines of a report - including inspect's sha verdict, or
+ * import's "This session had uncommitted changes. They were NOT applied." - and both
+ * commands exist precisely so a person can trust what they are reading before acting
+ * on it. `import` is the more dangerous of the two: its report ends in a command the
+ * reader is invited to run.
+ *
+ * Apply this to every string that came out of a bundle. Do NOT apply it to values the
+ * tool computed itself - counts, the locally-computed sha, literal labels, the temp
+ * patch path we created, the validated local root - because those are trusted and
+ * passing them through here only risks mangling legitimate output.
+ *
+ * Call it as `arr.map((s) => safe(s))`, NEVER as `arr.map(safe)`: map passes the index
+ * as the second argument, so `max` becomes 0 for the first element and every string is
+ * truncated to "…(truncated)".
+ */
+export function safe(s, max = 200) {
+    // eslint-disable-next-line no-control-regex
+    const stripped = s.replace(/[\x00-\x1f\x7f-\x9f]/g, "?");
+    return stripped.length > max ? stripped.slice(0, max) + "…(truncated)" : stripped;
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/transcript.js

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+export function readLines(text) {
+    return text.split("\n").filter((l) => l.length > 0);
+}
+/**
+ * Records are read one line at a time and never re-serialised. A line that
+ * does not parse is still counted and still shipped — the tool does not get
+ * to decide that a transcript is malformed.
+ */
+export function statTranscript(lines) {
+    const cwdCounts = {};
+    const versions = new Set();
+    for (const line of lines) {
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec && typeof rec === "object") {
+            const r = rec;
+            if (typeof r["cwd"] === "string") {
+                const c = r["cwd"];
+                cwdCounts[c] = (cwdCounts[c] ?? 0) + 1;
+            }
+            if (typeof r["version"] === "string")
+                versions.add(r["version"]);
+        }
+    }
+    return { recordCount: lines.length, cwdCounts, versions: [...versions].sort() };
+}
+export function deriveProjectRoot(stats) {
+    const entries = Object.entries(stats.cwdCounts);
+    if (entries.length === 0) {
+        throw new Error("no record in this transcript carries a cwd field; cannot determine the project root");
+    }
+    entries.sort((a, b) => b[1] - a[1]);
+    return { root: entries[0][0], ambiguous: entries.length > 1 };
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Swaps one prefix, everywhere, as plain text. Validates that from and to
+ * contain no quote or backslash, which would break JSON. Anchors the match
+ * to path boundaries to prevent sibling paths from being rewritten.
+ */
+export function rewritePrefix(lines, from, to) {
+    if (from.includes('"') || from.includes("\\")) {
+        throw new Error(`rewritePrefix: from argument contains quote or backslash: ${from}`);
+    }
+    if (to.includes('"') || to.includes("\\")) {
+        throw new Error(`rewritePrefix: to argument contains quote or backslash: ${to}`);
+    }
+    const re = new RegExp(escapeRegExp(from) + "(?![A-Za-z0-9._-])", "g");
+    let replaced = 0;
+    const out = lines.map((line) => line.replace(re, () => {
+        replaced += 1;
+        return to;
+    }));
+    return { lines: out, replaced };
+}
+// Matches paths that are sender-specific and not portable. Excludes /usr, /etc,
+// /bin, /opt: those are system paths that mean the same on both machines and
+// would flood the report if listed.
+const ABS_PATH = /(?:\/Users\/|\/home\/|\/root\/|\/tmp\/|\/private\/var\/|\/var\/folders\/)[A-Za-z0-9._+\-\/]+/g;
+/** Distinct absolute home-rooted or temp paths that are NOT under `root`, sorted. */
+export function unresolvedAbsolutePaths(lines, root) {
+    const found = new Set();
+    for (const line of lines) {
+        for (const m of line.matchAll(ABS_PATH)) {
+            if (!m[0].startsWith(root))
+                found.add(m[0]);
+        }
+    }
+    return [...found].sort();
+}
+export function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/**
+ * Replaces every occurrence of `from`, with NO path-boundary anchoring.
+ *
+ * rewritePrefix() anchors on a path boundary so that /Code/app cannot rewrite
+ * /Code/app2. That rule is wrong for a UUID: a session id is self-delimiting and
+ * cannot prefix a longer identifier, and the anchor actively breaks the common case
+ * of "<id>.jsonl", where the trailing "." reads as path continuation.
+ */
+export function replaceAllText(lines, from, to) {
+    if (/["\\]/.test(from)) {
+        throw new Error(`replaceAllText: from contains a quote or backslash: ${from}`);
+    }
+    if (/["\\]/.test(to)) {
+        throw new Error(`replaceAllText: to contains a quote or backslash: ${to}`);
+    }
+    let replaced = 0;
+    const out = lines.map((line) => {
+        const parts = line.split(from);
+        replaced += parts.length - 1;
+        return parts.join(to);
+    });
+    return { lines: out, replaced };
+}
+//# sourceMappingURL=transcript.js.map

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "csession",
+  "version": "0.1.0",
+  "description": "Move a Claude Code session between machines, or hand one to a peer.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "session",
+    "transcript",
+    "cli",
+    "transfer"
+  ],
+  "homepage": "https://github.com/jvsteiner/csession#readme",
+  "bugs": {
+    "url": "https://github.com/jvsteiner/csession/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jvsteiner/csession.git"
+  },
+  "author": "Jamie Steiner <jvsteiner@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "csession": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/**/*.js",
+    "!dist/**/*.test.js",
+    "!dist/testutil.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc && node --test 'dist/**/*.test.js'"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}