threadit-cli 0.2.0

package/dist/reconcileFormat.js

@@ -0,0 +1,30 @@
+/** Human-readable, class-grouped rendering of the unified proposal list. */
+export function formatProposals(proposals) {
+    if (proposals.length === 0)
+        return 'Nothing to reconcile — inbox drained, statuses honest, no loops.\n';
+    const inbox = proposals.filter((p) => p.class === 'inbox');
+    const status = proposals.filter((p) => p.class === 'status');
+    const loops = proposals.filter((p) => p.class === 'loop');
+    let out = 'Proposed dispositions (run with --apply to execute):\n';
+    if (inbox.length) {
+        out += '  Inbox:\n';
+        for (const p of inbox)
+            out += `    ${p.itemId} (seen ${p.seenCount}): ${p.suggested} — ${p.text}\n`;
+    }
+    if (status.length) {
+        out += '  Status:\n';
+        for (const p of status) {
+            const label = `${p.nodeId} [${p.finding}${p.forced ? '' : ', advisory'}]`;
+            // advisory findings omit suggested; print evidence only
+            out += p.suggested !== undefined
+                ? `    ${label}: ${p.suggested} — ${p.evidence}\n`
+                : `    ${label}: ${p.evidence}\n`;
+        }
+    }
+    if (loops.length) {
+        out += '  Loops (un-captured):\n';
+        for (const p of loops)
+            out += `    ${p.sha.slice(0, 8)}: ${p.suggested} — ${p.subject}\n`;
+    }
+    return out;
+}

package/dist/session.d.ts

@@ -0,0 +1,4 @@
+/** The current session number (0 when never initialized / bumped). */
+export declare function readSession(repoRoot: string): number;
+/** Increment the session counter, persist it, and return the new value. */
+export declare function bumpSession(repoRoot: string): number;

package/dist/session.js

@@ -0,0 +1,11 @@
+import { readConfig, updateConfig } from './config.js';
+/** The current session number (0 when never initialized / bumped). */
+export function readSession(repoRoot) {
+    return readConfig(repoRoot).session ?? 0;
+}
+/** Increment the session counter, persist it, and return the new value. */
+export function bumpSession(repoRoot) {
+    const next = readSession(repoRoot) + 1;
+    updateConfig(repoRoot, { session: next });
+    return next;
+}

package/dist/transport/sync.d.ts

@@ -0,0 +1,38 @@
+import type { ChainEntry } from '../git/log.js';
+export interface RevisionPayload {
+    projectId: string;
+    sha: string;
+    parentSha: string | null;
+    authorDate: string;
+    fileBlob: string;
+    trailers: string[];
+    touchedPaths: string[];
+}
+export interface DraftPayload {
+    projectId: string;
+    sessionKey: string;
+    fileBlob: string;
+}
+export interface SyncDeps {
+    fetch: typeof globalThis.fetch;
+}
+/** Build ingest payloads (oldest-first) from a newest-first chain + per-sha lookups. */
+export declare function buildRevisionPayloads(projectId: string, chainNewestFirst: ChainEntry[], blobAt: (sha: string) => string | null, trailersAt: (sha: string) => string[], pathsAt: (sha: string) => string[]): RevisionPayload[];
+export interface IngestServerInfo {
+    serverProtocol: number;
+    serverVersion: string;
+}
+export declare function postIngest(server: string, token: string, payload: RevisionPayload, deps: SyncDeps): Promise<IngestServerInfo>;
+export declare function postDraft(server: string, token: string, payload: DraftPayload, deps: SyncDeps): Promise<void>;
+export interface InboxPayload {
+    projectId: string;
+    fileBlob: string;
+}
+export declare function postInbox(server: string, token: string, payload: InboxPayload, deps: SyncDeps): Promise<void>;
+/** The full current first-parent sha set, sent on a detected history rewrite so the server purges
+ *  orphaned shas (rebase/amend/force-push auto-recovery). */
+export interface ManifestPayload {
+    projectId: string;
+    shas: string[];
+}
+export declare function postManifest(server: string, token: string, payload: ManifestPayload, deps: SyncDeps): Promise<void>;

package/dist/transport/sync.js

@@ -0,0 +1,64 @@
+import { INGEST_PROTOCOL } from '@threadit/core';
+import { PACK_VERSION } from '../version.js';
+/** Build ingest payloads (oldest-first) from a newest-first chain + per-sha lookups. */
+export function buildRevisionPayloads(projectId, chainNewestFirst, blobAt, trailersAt, pathsAt) {
+    const payloads = [];
+    for (const entry of [...chainNewestFirst].reverse()) { // oldest-first
+        const fileBlob = blobAt(entry.sha);
+        if (fileBlob === null)
+            continue; // threadit.yml didn't exist at this revision — skip
+        payloads.push({
+            projectId,
+            sha: entry.sha,
+            parentSha: entry.parent,
+            authorDate: entry.authorDate,
+            fileBlob,
+            trailers: trailersAt(entry.sha),
+            touchedPaths: pathsAt(entry.sha),
+        });
+    }
+    return payloads;
+}
+export async function postIngest(server, token, payload, deps) {
+    const res = await deps.fetch(`${server}/projects/${payload.projectId}/ingest`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}`,
+            'X-Threadit-Protocol': String(INGEST_PROTOCOL), 'X-Threadit-Client': PACK_VERSION }, // X-Threadit-Client is one-way: server logs/ignores it; advisory is computed client-side
+        body: JSON.stringify(payload),
+    });
+    if (res.status === 409) {
+        const b = await res.json().catch(() => ({}));
+        throw new Error(`ingest rejected (protocol): ${b.message ?? 'version incompatible'}`);
+    }
+    if (!res.ok)
+        throw new Error(`ingest ${payload.sha} failed: HTTP ${res.status}`);
+    const b = await res.json().catch(() => ({}));
+    return { serverProtocol: b.serverProtocol ?? INGEST_PROTOCOL, serverVersion: b.serverVersion ?? '0.0.0' };
+}
+export async function postDraft(server, token, payload, deps) {
+    const res = await deps.fetch(`${server}/projects/${payload.projectId}/draft`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok)
+        throw new Error(`draft sync failed: HTTP ${res.status}`);
+}
+export async function postInbox(server, token, payload, deps) {
+    const res = await deps.fetch(`${server}/projects/${payload.projectId}/inbox-sync`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok)
+        throw new Error(`inbox sync failed: HTTP ${res.status}`);
+}
+export async function postManifest(server, token, payload, deps) {
+    const res = await deps.fetch(`${server}/projects/${payload.projectId}/sync-manifest`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok)
+        throw new Error(`sync-manifest failed: HTTP ${res.status}`);
+}

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+export declare const PACK_VERSION: string;
+/** A dev/prerelease/unbumped version that must never trigger a drift nudge. */
+export declare function isDevVersion(v: string): boolean;
+/** True iff `a` is strictly older than `b` (semver core compare). Equal/newer → false. */
+export declare function isOlder(a: string, b: string): boolean;

package/dist/version.js

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+function readPkgVersion() {
+    try {
+        // src/version.ts (vitest) or dist/version.js (shipped) → ../package.json at the package root
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export const PACK_VERSION = readPkgVersion();
+/** A dev/prerelease/unbumped version that must never trigger a drift nudge. */
+export function isDevVersion(v) {
+    return v === '0.0.0' || v.includes('-');
+}
+function triple(v) {
+    const core = v.split('-')[0];
+    const [a, b, c] = core.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    return [a ?? 0, b ?? 0, c ?? 0];
+}
+/** True iff `a` is strictly older than `b` (semver core compare). Equal/newer → false. */
+export function isOlder(a, b) {
+    const [a0, a1, a2] = triple(a);
+    const [b0, b1, b2] = triple(b);
+    if (a0 !== b0)
+        return a0 < b0;
+    if (a1 !== b1)
+        return a1 < b1;
+    return a2 < b2;
+}

package/dist/yaml/emit.d.ts

@@ -0,0 +1,3 @@
+import type { ParsedThreaditFile, ParsedInboxFile } from '@threadit/core';
+export declare function emitThreaditFile(file: ParsedThreaditFile): string;
+export declare function emitInboxFile(inbox: ParsedInboxFile): string;

package/dist/yaml/emit.js

@@ -0,0 +1,50 @@
+import { stringify } from 'yaml';
+const NODE_KEY_ORDER = [
+    'id', 'parent', 'order', 'title', 'status', 'flow', 'milestone', 'main',
+    'summary', 'summary_at', 'detail', 'work', 'paths', 'docs',
+    'blocked_by', 'born_from', 'superseded_by', 'folded_into', 'renamed_from', 'related',
+    'until', 'decisions', 'at',
+];
+const INBOX_ITEM_KEY_ORDER = [
+    'id', 'text', 'created', 'source', 'session_id', 'status',
+    'seen_count', 'seen_at', 'snooze_until', 'promoted_to', 'related', 'tags', 'note', 'risk_node',
+];
+/**
+ * Reorder an object's present keys into a fixed canonical order.
+ *
+ * Contract: a key whose value is `undefined` is OMITTED; a key whose value is `null`
+ * is EMITTED as `null`. Callers clearing a nullable field must `delete` the key (omit) —
+ * setting it to `undefined` drops it; the field's absence vs explicit null is meaningful.
+ */
+function orderKeys(obj, keyOrder) {
+    const out = {};
+    for (const k of keyOrder)
+        if (obj[k] !== undefined)
+            out[k] = obj[k];
+    for (const k of Object.keys(obj))
+        if (!keyOrder.includes(k) && obj[k] !== undefined)
+            out[k] = obj[k];
+    return out;
+}
+export function emitThreaditFile(file) {
+    const doc = { threadit: file.threadit, project: file.project };
+    // omit optional top-level keys rather than emit them as null
+    if (file.sessions !== undefined)
+        doc.sessions = file.sessions;
+    if (file.wrapup !== undefined)
+        doc.wrapup = file.wrapup;
+    if (file.reconcile !== undefined)
+        doc.reconcile = file.reconcile;
+    if (file.epochs !== undefined)
+        doc.epochs = file.epochs;
+    doc.nodes = file.nodes.map((n) => orderKeys(n, NODE_KEY_ORDER));
+    return stringify(doc, { lineWidth: 0 }); // lineWidth 0 = no line-wrap: stable canonical emit across editors
+}
+export function emitInboxFile(inbox) {
+    const doc = {
+        threadit_inbox: inbox.threadit_inbox,
+        project: inbox.project,
+        items: inbox.items.map((i) => orderKeys(i, INBOX_ITEM_KEY_ORDER)),
+    };
+    return stringify(doc, { lineWidth: 0 }); // lineWidth 0 = no line-wrap: stable canonical emit across editors
+}

package/dist/yaml/io.d.ts

@@ -0,0 +1,11 @@
+import type { ParsedThreaditFile, ParsedInboxFile, StructuralError } from '@threadit/core';
+export declare class ValidationFailure extends Error {
+    readonly errors: StructuralError[];
+    constructor(errors: StructuralError[]);
+}
+export declare function loadThreadit(path: string): ParsedThreaditFile;
+/** Persist a threadit.yml ONLY if it passes the structural gate (valid by construction). */
+export declare function saveThreadit(path: string, file: ParsedThreaditFile): void;
+export declare function loadInbox(path: string): ParsedInboxFile;
+/** Inbox has no structural gate; re-parse the emitted text to guarantee it is well-formed. */
+export declare function saveInbox(path: string, inbox: ParsedInboxFile): void;

package/dist/yaml/io.js

@@ -0,0 +1,33 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { engine, parseThreaditFile, parseInboxFile } from '@threadit/core';
+import { emitThreaditFile, emitInboxFile } from './emit.js';
+export class ValidationFailure extends Error {
+    errors;
+    constructor(errors) {
+        super('Refusing to write: threadit.yml would be structurally invalid:\n' +
+            errors.map((e) => `  ${e.kind} at ${e.at}: ${e.message}`).join('\n'));
+        this.errors = errors;
+        this.name = 'ValidationFailure';
+    }
+}
+export function loadThreadit(path) {
+    return parseThreaditFile(readFileSync(path, 'utf8'));
+}
+/** Persist a threadit.yml ONLY if it passes the structural gate (valid by construction). */
+export function saveThreadit(path, file) {
+    const result = engine({ file });
+    if (result.structuralErrors.length > 0)
+        throw new ValidationFailure(result.structuralErrors);
+    const text = emitThreaditFile(file);
+    parseThreaditFile(text); // guard: emitted text must round-trip through the parser
+    writeFileSync(path, text, 'utf8');
+}
+export function loadInbox(path) {
+    return parseInboxFile(readFileSync(path, 'utf8'));
+}
+/** Inbox has no structural gate; re-parse the emitted text to guarantee it is well-formed. */
+export function saveInbox(path, inbox) {
+    const text = emitInboxFile(inbox);
+    parseInboxFile(text); // throws ThreaditParseError if we produced something invalid
+    writeFileSync(path, text, 'utf8');
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "threadit-cli",
+  "version": "0.2.0",
+  "type": "module",
+  "bin": {
+    "threadit": "./dist/bin.js"
+  },
+  "main": "./dist/bin.js",
+  "exports": {
+    ".": {
+      "types": "./dist/bin.d.ts",
+      "default": "./dist/bin.js"
+    }
+  },
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@threadit/core": "^0.2.0",
+    "commander": "^12.1.0",
+    "picomatch": "^4.0.2",
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/picomatch": "^3.0.1"
+  }
+}