lattris 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# lattris
+
+First-party command-line client for [Lattris](https://lattris.com) — sign in, capture
+notes and sessions, and read your own tree from the terminal.
+
+## Install
+
+```bash
+npm install -g lattris
+```
+
+Requires Node.js 22 or newer. The package ships compiled JavaScript only; there is no
+build step and no postinstall script.
+
+## Sign in
+
+```bash
+lattris login
+```
+
+That opens your browser and completes an authorization-code sign-in with PKCE. On a
+machine with no browser — a server, a container, a remote shell — use the device flow
+instead and enter the code it prints on any other device:
+
+```bash
+lattris login --device
+```
+
+Both leave you signed in on that machine. `lattris logout` ends it.
+
+```bash
+lattris whoami
+```
+
+confirms who you are signed in as, and exits non-zero when you are not signed in, so it
+is safe to use as a guard in a script.
+
+**You need an account first.** Lattris is invite-only; the CLI signs you in, it does not
+sign you up.
+
+## What it does
+
+```
+lattris capture      write a note or start a session
+lattris note         a single note
+lattris session      a session and its turns
+lattris recording    a recording and its transcript
+lattris memory       read and manage blocks
+lattris link         connect two blocks
+lattris get          read a block
+lattris ask          ask a question of a tree
+lattris invite       invite someone
+lattris contact      manage contacts
+```
+
+Run `lattris help <command>` for any of them, or `lattris --help` for the full list.
+
+## Where it keeps things
+
+Credentials live in your user config directory and are readable only by you. `lattris
+logout` removes them. Nothing is written to the directory you run it from.
+
+## Verifying what you installed
+
+Releases published through CI carry [npm provenance](https://docs.npmjs.com/generating-provenance-statements):
+the registry records an attestation linking the tarball to the commit on `main` it was
+built from and the workflow run that built it. The first published version was published
+by hand to claim the name and carries no attestation, so do not assume one — check:
+
+```bash
+npm audit signatures
+```
+
+That is a statement about the version you installed from the registry. It says nothing
+about a copy obtained any other way.
+
+## Source, terms and reporting
+
+This is proprietary software. The source is not public, and `UNLICENSED` is
+deliberate rather than an oversight: formal terms of use are still to follow.
+Nothing here grants you rights beyond installing and running the tool, and no
+permission should be inferred from the absence of a licence file.
+
+There is no public issue tracker, so this package names none — a link you cannot
+open is worse than no link. For terms, faults or anything else, write to
+series@lattris.com.

package/dist/extract-claude-jsonl.js

@@ -0,0 +1,253 @@
+// Deterministic extractor: a Claude Code transcript
+// (~/.claude/projects/<project>/<session>.jsonl) in, ordered epoch turns out
+// (session-block spec §Skill — each rule verified against a real
+// transcript corpus, never inferred from vendor docs).
+// Extraction is MECHANICAL — one place for this vendor's shape, zero
+// judgment: the same file always yields the same epochs, byte for byte.
+// The AI-judgment touchpoints (when to save, title, ai_summary) live in the
+// skill, never here.
+//
+// An internal module behind `lattris capture session <transcript.jsonl>`
+// (main.ts) — not a command of its own.
+//
+// The settled extraction rules, in the spec's own words:
+// - The transcript is a TREE, not a list: every entry carries uuid/
+//   parentUuid; the conversation is the walk from the live leaf up, never
+//   file line order. Dead branches (rewinds) stay in the file and are simply
+//   not on the walked path.
+// - The chain break at compaction: the system/compact_boundary entry has
+//   parentUuid null; continuity is its logicalParentUuid — a naive
+//   parent-walk silently truncates at the last compaction, so the walk
+//   bridges it. Each boundary starts a NEW EPOCH; the summary rides the
+//   isCompactSummary user entry and becomes the next epoch's opening
+//   kind: 'compaction-summary' marker turn.
+// - Most "user" entries are not the person: promptSource 'typed' +
+//   origin.kind 'human' is the person; tool_result carriers, meta entries
+//   and task notifications are machinery; isSidechain entries are subagent
+//   noise — all stripped.
+// - Thinking blocks are OUT (private scratchpad, not dialogue); an
+//   assistant turn is its message's text blocks only, and one API message
+//   spans MULTIPLE jsonl entries (one content block each, same message.id)
+//   — concatenated in path order.
+// - Peer-session messages are stamped as their own speaker
+//   (peer:<origin.name>), never the owner; the body is origin.body (the
+//   raw message, without the harness's delivery wrapper).
+// - Two file shapes. A MAIN transcript is the person's session; sidechain
+//   entries inside it are a subagent's turns interleaved, and noise. A
+//   SUBAGENT transcript (…/<session>/subagents/agent-<id>.jsonl) is that
+//   subagent's own file: every path entry is isSidechain with an agentId,
+//   its first user entry is the parent's prompt (no promptSource, no
+//   origin), and its later user entries are tool_result carriers. The
+//   shape is read from the file and named on the result, and the same
+//   chain of epochs comes out of either.
+//
+// Zero imports beyond node built-ins, mirroring main.ts's own discipline.
+const parseLines = (jsonl) => {
+    const entries = [];
+    for (const line of jsonl.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === 'object')
+                entries.push(parsed);
+        }
+        catch {
+            // A torn tail line (the file is appended live) is not a conversation
+            // fact — skipped, deterministically.
+        }
+    }
+    return entries;
+};
+// Path-bearing entries: the tree the walk runs over. Everything else
+// (attachments, file-history, queue bookkeeping…) never carries dialogue.
+const isPathEntry = (e) => typeof e.uuid === 'string' &&
+    (e.type === 'user' || e.type === 'assistant' || e.type === 'system');
+// The ACTIVE path, live leaf up, oldest-first on return.
+// The live leaf is the LAST path-bearing entry in file order — the file is
+// an append log, so its tail is the current tip; every dead branch hangs off
+// an earlier fork and is unreachable walking UP from here. The compaction
+// bridge: parentUuid null + logicalParentUuid set continues the walk into
+// the previous epoch.
+export const walkActivePath = (entries) => {
+    const byUuid = new Map();
+    for (const e of entries) {
+        if (typeof e.uuid === 'string')
+            byUuid.set(e.uuid, e);
+    }
+    let cursor = [...entries].reverse().find(isPathEntry);
+    const path = [];
+    const seen = new Set();
+    while (cursor) {
+        if (typeof cursor.uuid !== 'string' || seen.has(cursor.uuid))
+            break; // cycle guard
+        seen.add(cursor.uuid);
+        path.push(cursor);
+        const parentId = cursor.parentUuid ?? cursor.logicalParentUuid;
+        cursor = typeof parentId === 'string' ? byUuid.get(parentId) : undefined;
+    }
+    return path.reverse();
+};
+const textOf = (content) => {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('\n\n');
+};
+// The shape of a FILE, judged over every path-bearing entry before any
+// walk: a subagent's own file has all of them marked isSidechain with an
+// agentId; anything else is a main transcript, where a sidechain entry is
+// another agent's turn and noise, even at the file's tail. Judged before
+// the walk because the walk starts at the last path entry in file order,
+// and a main file whose tail is a subagent's appended turns would
+// otherwise be walked from the subagent's leaf.
+export const shapeOf = (entries) => {
+    const bearing = entries.filter(isPathEntry);
+    return bearing.length > 0 &&
+        bearing.every((e) => e.isSidechain === true && typeof e.agentId === 'string')
+        ? 'subagent'
+        : 'main';
+};
+const carriesToolResult = (content) => Array.isArray(content) &&
+    content.some((b) => b && typeof b === 'object' && b.type === 'tool_result');
+export const classify = (e, shape = 'main') => {
+    if (shape === 'main' && e.isSidechain === true)
+        return { kind: 'noise' };
+    if (e.type === 'system') {
+        return e.subtype === 'compact_boundary'
+            ? { kind: 'epoch-boundary', entry: e }
+            : { kind: 'noise' };
+    }
+    if (e.type === 'user') {
+        // The compaction summary — identified by its flag BEFORE any
+        // person/machinery classification (it is neither).
+        if (e.isCompactSummary === true) {
+            const text = textOf(e.message?.content);
+            return text.trim().length > 0 ? { kind: 'marker', text, entry: e } : { kind: 'noise' };
+        }
+        if (e.origin?.kind === 'peer') {
+            const name = typeof e.origin.name === 'string' && e.origin.name.length > 0 ? e.origin.name : 'unknown';
+            // origin.body is the raw peer message; the entry's own content wraps
+            // it in the harness's delivery boilerplate, which is machinery.
+            const body = typeof e.origin.body === 'string' ? e.origin.body : textOf(e.message?.content);
+            return body.trim().length > 0
+                ? { kind: 'peer', speaker: `peer:${name}`, text: body, entry: e }
+                : { kind: 'noise' };
+        }
+        if (e.promptSource === 'typed' && e.origin?.kind === 'human' && e.isMeta !== true) {
+            const text = textOf(e.message?.content);
+            return text.trim().length > 0 ? { kind: 'person', text, entry: e } : { kind: 'noise' };
+        }
+        // In a subagent's own file the parent's prompt carries no promptSource
+        // and no origin: it is the user entry that is words and not a
+        // tool_result carrier.
+        if (shape === 'subagent' && e.isMeta !== true && !carriesToolResult(e.message?.content)) {
+            const text = textOf(e.message?.content);
+            return text.trim().length > 0 ? { kind: 'person', text, entry: e } : { kind: 'noise' };
+        }
+        // tool_result carriers, meta entries, task notifications, queued
+        // machinery — not dialogue.
+        return { kind: 'noise' };
+    }
+    if (e.type === 'assistant') {
+        // Text blocks only — thinking is OUT (deliberate: private scratchpad,
+        // never dialogue), tool_use is
+        // machinery. One entry carries one block; same-message entries merge in
+        // the caller.
+        const text = textOf(e.message?.content);
+        return text.trim().length > 0
+            ? { kind: 'assistant-block', messageId: e.message?.id, text, entry: e }
+            : { kind: 'noise' };
+    }
+    return { kind: 'noise' };
+};
+const toTurn = (speaker, text, entry, kind) => {
+    const turn = { speaker, text };
+    if (typeof entry.timestamp === 'string')
+        turn.saidAt = entry.timestamp;
+    if (kind !== undefined)
+        turn.kind = kind;
+    if (typeof entry.uuid === 'string')
+        turn.externalMessageId = entry.uuid;
+    const parent = entry.parentUuid ?? entry.logicalParentUuid;
+    if (typeof parent === 'string')
+        turn.externalParentMessageId = parent;
+    return turn;
+};
+// The whole extraction: entries → active path → epochs of ordered turns.
+export const extractChain = (jsonl) => {
+    const entries = parseLines(jsonl);
+    const shape = shapeOf(entries);
+    // In a main file the sidechain entries are noise before the walk too, so
+    // the live leaf is the person's last word and never a subagent's.
+    const path = walkActivePath(shape === 'main' ? entries.filter((e) => e.isSidechain !== true) : entries);
+    const agentId = shape === 'subagent'
+        ? (path.map((e) => e.agentId).find((a) => typeof a === 'string') ?? null)
+        : null;
+    const sessionId = path.map((e) => e.sessionId).find((s) => typeof s === 'string') ?? null;
+    // A subagent's conversation identity is its own: the parent's session id
+    // and its agent id together, distinct from the parent's and from every
+    // sibling's, the same on every capture of the same file. The receipts and
+    // the conversation nomination key on it, so two siblings captured under
+    // one session never extend or fork each other. Joined with a separator a
+    // file name can carry, since the receipts file is named by it.
+    const conversationId = shape === 'subagent' && sessionId !== null && agentId !== null
+        ? `${sessionId}--agent-${agentId}`
+        : sessionId;
+    const epochs = [];
+    let current = [];
+    // The assistant merge: consecutive path entries sharing message.id are
+    // one API message — their text blocks concatenate into ONE turn (path
+    // order), stamped with the FIRST entry's ids/time.
+    let pendingAssistant = null;
+    const flushAssistant = () => {
+        if (!pendingAssistant)
+            return;
+        current.push(toTurn('assistant', pendingAssistant.texts.join('\n\n'), pendingAssistant.entry));
+        pendingAssistant = null;
+    };
+    for (const e of path) {
+        const c = classify(e, shape);
+        if (c.kind === 'assistant-block') {
+            if (pendingAssistant &&
+                pendingAssistant.messageId === c.messageId &&
+                c.messageId !== undefined) {
+                pendingAssistant.texts.push(c.text);
+            }
+            else {
+                flushAssistant();
+                pendingAssistant = { messageId: c.messageId, texts: [c.text], entry: c.entry };
+            }
+            continue;
+        }
+        if (c.kind === 'noise')
+            continue;
+        flushAssistant();
+        if (c.kind === 'epoch-boundary') {
+            // A new epoch begins. The boundary itself carries no words — the
+            // summary marker (the next epoch's first classified entry) does.
+            if (current.length > 0)
+                epochs.push(current);
+            current = [];
+            continue;
+        }
+        if (c.kind === 'marker') {
+            current.push(toTurn('system', c.text, c.entry, 'compaction-summary'));
+            continue;
+        }
+        if (c.kind === 'person') {
+            current.push(toTurn('user', c.text, c.entry));
+            continue;
+        }
+        current.push(toTurn(c.speaker, c.text, c.entry));
+    }
+    flushAssistant();
+    if (current.length > 0)
+        epochs.push(current);
+    return { source: 'claude-code', conversationId, shape, agentId, epochs };
+};
+//# sourceMappingURL=extract-claude-jsonl.js.map