@alexgsdev/claude-code-transcript-export 0.1.0

package/dist/write.d.ts

@@ -0,0 +1,61 @@
+import type { SessionImage } from './types.js';
+/**
+ * Writes `render(date)` to `path` unless the file there already says the same
+ * thing. Returns whether it wrote.
+ *
+ * The date is preserved when the content around it is identical, so
+ * `extracted:` comes to mean "the day this transcript last changed" rather than
+ * "the day the extractor last ran". Without that, a rerun touches every
+ * transcript and the resulting commit is a wall of one-line diffs with nothing
+ * in it — the shape of a diff nobody reads, in the one directory where a real
+ * change to an old transcript would matter.
+ *
+ * Takes a render *function* rather than a string so the prior date can be fed
+ * back in. The renderer stays pure; the impurity lives here, where the I/O
+ * already is.
+ */
+export declare function writeIfChanged(path: string, render: (extractedOn: string) => string, today: string): boolean;
+/** Writes a file only when its bytes differ. For output with no date header. */
+export declare function writePlainIfChanged(path: string, contents: string): boolean;
+/**
+ * Writes images that are not already on disk.
+ *
+ * Filenames are content hashes, so an existing file with the right name always
+ * has the right bytes and never needs rewriting.
+ */
+export declare function writeImages(dir: string, images: SessionImage[]): string[];
+/**
+ * Deletes transcripts left behind when a session was renamed.
+ *
+ * A filename is built from the session's title, and a title is whatever the
+ * last `custom-title` or `ai-title` record says. Sessions get renamed as they
+ * go, so a session extracted twice across a rename lands under two names.
+ * Writing never removes the first, and the stale copy stays: a truncated
+ * transcript that reads exactly like evidence, absent from the index, citable
+ * by anyone who finds it.
+ *
+ * **Scoped to renames, never a directory sync.** A file is removed only when
+ * this run wrote a different name for the same session id. The logs are
+ * ephemeral and the output is the durable record, so a transcript whose JSONL
+ * has since been pruned must survive; a sync would delete precisely the
+ * transcripts that can no longer be regenerated.
+ */
+export declare function pruneRenamed(outDir: string, written: string[]): string[];
+/**
+ * Deletes transcripts for sessions the config now excludes.
+ *
+ * Without this, adding a UUID to `exclude` does nothing to what is already on
+ * disk, which is the opposite of what the user asked for.
+ */
+export declare function pruneExcluded(outDir: string, excludedIds: string[]): string[];
+/**
+ * Images in `imageDir` that no transcript references.
+ *
+ * **Reported, never deleted.** Content-hash naming makes "unreferenced" an
+ * exact fact rather than a guess, so the report is trustworthy — but an image
+ * is the one output that cannot be regenerated once its log is pruned, which
+ * puts it on the wrong side of the rule that this tool never deletes what it
+ * cannot rebuild.
+ */
+export declare function findOrphanImages(imageDir: string, referenced: Set<string>): string[];
+//# sourceMappingURL=write.d.ts.map

package/dist/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,EACvC,KAAK,EAAE,MAAM,GACZ,OAAO,CAST;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI3E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,EAAE,CAYzE;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAkBxE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAa7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAKpF"}

package/dist/write.js

@@ -0,0 +1,126 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { readExtractedDate } from './render/transcript.js';
+/**
+ * Writes `render(date)` to `path` unless the file there already says the same
+ * thing. Returns whether it wrote.
+ *
+ * The date is preserved when the content around it is identical, so
+ * `extracted:` comes to mean "the day this transcript last changed" rather than
+ * "the day the extractor last ran". Without that, a rerun touches every
+ * transcript and the resulting commit is a wall of one-line diffs with nothing
+ * in it — the shape of a diff nobody reads, in the one directory where a real
+ * change to an old transcript would matter.
+ *
+ * Takes a render *function* rather than a string so the prior date can be fed
+ * back in. The renderer stays pure; the impurity lives here, where the I/O
+ * already is.
+ */
+export function writeIfChanged(path, render, today) {
+    if (existsSync(path)) {
+        const existing = readFileSync(path, 'utf8');
+        const prior = readExtractedDate(existing);
+        if (prior !== null && render(prior) === existing)
+            return false;
+    }
+    writeFileSync(path, render(today));
+    return true;
+}
+/** Writes a file only when its bytes differ. For output with no date header. */
+export function writePlainIfChanged(path, contents) {
+    if (existsSync(path) && readFileSync(path, 'utf8') === contents)
+        return false;
+    writeFileSync(path, contents);
+    return true;
+}
+/**
+ * Writes images that are not already on disk.
+ *
+ * Filenames are content hashes, so an existing file with the right name always
+ * has the right bytes and never needs rewriting.
+ */
+export function writeImages(dir, images) {
+    if (images.length === 0)
+        return [];
+    mkdirSync(dir, { recursive: true });
+    const written = [];
+    for (const image of images) {
+        const path = join(dir, image.filename);
+        if (existsSync(path))
+            continue;
+        writeFileSync(path, image.data);
+        written.push(image.filename);
+    }
+    return written;
+}
+/** `<date>--<slug>--<8 hex>.md`, the shape `sessionFilename` writes. */
+const TRANSCRIPT_NAME = /^\d{4}-\d{2}-\d{2}--.+--([0-9a-f]{8})\.md$/;
+/**
+ * Deletes transcripts left behind when a session was renamed.
+ *
+ * A filename is built from the session's title, and a title is whatever the
+ * last `custom-title` or `ai-title` record says. Sessions get renamed as they
+ * go, so a session extracted twice across a rename lands under two names.
+ * Writing never removes the first, and the stale copy stays: a truncated
+ * transcript that reads exactly like evidence, absent from the index, citable
+ * by anyone who finds it.
+ *
+ * **Scoped to renames, never a directory sync.** A file is removed only when
+ * this run wrote a different name for the same session id. The logs are
+ * ephemeral and the output is the durable record, so a transcript whose JSONL
+ * has since been pruned must survive; a sync would delete precisely the
+ * transcripts that can no longer be regenerated.
+ */
+export function pruneRenamed(outDir, written) {
+    if (!existsSync(outDir))
+        return [];
+    const keep = new Set(written);
+    const writtenIds = new Set(written.map((name) => TRANSCRIPT_NAME.exec(name)?.[1]).filter(Boolean));
+    const removed = readdirSync(outDir)
+        .filter((name) => !keep.has(name))
+        .filter((name) => {
+        const id = TRANSCRIPT_NAME.exec(name)?.[1];
+        return id !== undefined && writtenIds.has(id);
+    })
+        .sort();
+    for (const name of removed)
+        rmSync(join(outDir, name));
+    return removed;
+}
+/**
+ * Deletes transcripts for sessions the config now excludes.
+ *
+ * Without this, adding a UUID to `exclude` does nothing to what is already on
+ * disk, which is the opposite of what the user asked for.
+ */
+export function pruneExcluded(outDir, excludedIds) {
+    if (!existsSync(outDir) || excludedIds.length === 0)
+        return [];
+    const prefixes = new Set(excludedIds.map((id) => id.slice(0, 8)));
+    const removed = readdirSync(outDir)
+        .filter((name) => {
+        const id = TRANSCRIPT_NAME.exec(name)?.[1];
+        return id !== undefined && prefixes.has(id);
+    })
+        .sort();
+    for (const name of removed)
+        rmSync(join(outDir, name));
+    return removed;
+}
+/**
+ * Images in `imageDir` that no transcript references.
+ *
+ * **Reported, never deleted.** Content-hash naming makes "unreferenced" an
+ * exact fact rather than a guess, so the report is trustworthy — but an image
+ * is the one output that cannot be regenerated once its log is pruned, which
+ * puts it on the wrong side of the rule that this tool never deletes what it
+ * cannot rebuild.
+ */
+export function findOrphanImages(imageDir, referenced) {
+    if (!existsSync(imageDir))
+        return [];
+    return readdirSync(imageDir)
+        .filter((name) => !referenced.has(name))
+        .sort();
+}
+//# sourceMappingURL=write.js.map

package/dist/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@alexgsdev/claude-code-transcript-export",
+  "version": "0.1.0",
+  "description": "Extract Claude Code session logs into readable, committable markdown transcripts.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "transcript",
+    "export",
+    "jsonl"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexgs/claude-code-transcript-export.git"
+  },
+  "homepage": "https://github.com/alexgs/claude-code-transcript-export#readme",
+  "bugs": {
+    "url": "https://github.com/alexgs/claude-code-transcript-export/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "cctx": "dist/cli/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "prettier": "^3.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "volta": {
+    "node": "22.23.2",
+    "npm": "11.5.2"
+  }
+}