@treeseed/dsh-chapters 0.1.0

package/lib/render.js

@@ -0,0 +1,280 @@
+/**
+ * Chapter renderer: durable events in a seq range → one Markdown file, deterministically.
+ *
+ * This module is pure and cordis-free. The model never writes chapter text (invariant 4 in AGENTS.md) — it
+ * supplies ranges, and every byte of the body comes from the log. So correctness here IS the "retrievable
+ * memory" promise.
+ *
+ * Two hazards this file exists to handle:
+ *
+ * 1. **Fence collision.** Conversation text routinely contains ``` blocks. A Markdown file that embeds a
+ *    triple-backtick fence inside a triple-backtick fence terminates early and silently truncates the rest
+ *    of the chapter. `longerFence()` solves this by measuring the longest backtick run in the payload and
+ *    using one longer. Verified by test, because the failure is invisible by eye.
+ * 2. **Silent holes.** An event that renders to nothing must never vanish quietly — it is recorded in
+ *    `stats.unrenderedSeqs` so a gap becomes a visible assertion rather than lost history.
+ * 3. **Borrowed context.** Host-injected instruction/snapshot/catalog text is project state, not
+ *    conversation: it is screened at this chokepoint (src/injections.ts) and replaced by a countable
+ *    marker, so a project's own docs never travel in the shared knowledge corpus.
+ */
+import { createHash } from 'node:crypto';
+import { DEFAULT_REDACTIONS, redactText } from "./redact.js";
+import { omittedMarker, screenConversation, stripReminderSpans } from "./injections.js";
+/** chars/4 until the host tokenMeter is wired in. Labelled an estimate everywhere it surfaces. */
+export const estimateTokens = (text) => Math.ceil(text.length / 4);
+/**
+ * A fence strictly longer than any backtick run inside `body`, so embedded code blocks cannot close it.
+ * Markdown requires the closing fence to be at least as long as the opening one.
+ */
+export function longerFence(body) {
+    let max = 0;
+    for (const match of body.matchAll(/`+/g))
+        max = Math.max(max, match[0].length);
+    return '`'.repeat(Math.max(3, max + 1));
+}
+/** Wrapped in a fence long enough to survive any content, including nested fences. */
+export function fenced(content, info = '') {
+    const fence = longerFence(content);
+    return `${fence}${info}\n${content}\n${fence}`;
+}
+export const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
+/** `artifacts/8f/8f3a1c9d….txt` — sharded so one directory never holds the whole subtree. */
+export const artifactPath = (hash) => `artifacts/${hash.slice(0, 2)}/${hash}.txt`;
+export function artifactRef(text, opts) {
+    const hash = sha256(text);
+    return {
+        sha256: hash,
+        path: artifactPath(hash),
+        bytes: Buffer.byteLength(text, 'utf8'),
+        content: text,
+        inlined: opts.inlined,
+        toolName: opts.toolName,
+        sourceSeq: opts.sourceSeq,
+    };
+}
+const blocksOf = (value) => Array.isArray(value) ? value : [];
+const textOf = (value) => blocksOf(value)
+    .filter((b) => b.type === 'text')
+    .map((b) => b.text ?? '')
+    .join('\n');
+/** Flatten a tool-result payload, which nests a content array inside a tool-result block. */
+function toolResultText(data) {
+    const message = data.message;
+    const inner = blocksOf(message?.content ?? data.content);
+    const parts = [];
+    for (const block of inner) {
+        if (block.type === 'text')
+            parts.push(block.text ?? '');
+        else if (block.type === 'tool-result') {
+            const nested = block.content;
+            parts.push(typeof nested === 'string' ? nested : textOf(nested));
+        }
+    }
+    return parts.filter((p) => p.length > 0).join('\n');
+}
+/**
+ * Validate model-supplied ranges. Never trust them (hard rule): an overlap duplicates archived text and a
+ * gap silently drops history, so both are errors here rather than data that quietly goes missing.
+ */
+export function validateRanges(chapters, archiveCeiling) {
+    if (chapters.length === 0)
+        throw new Error('no chapters supplied');
+    chapters.forEach((c, i) => {
+        if (c.startSeq > c.endSeq) {
+            throw new Error(`chapter ${i} ("${c.title}") has startSeq ${c.startSeq} above endSeq ${c.endSeq}`);
+        }
+        if (c.endSeq > archiveCeiling) {
+            throw new Error(`chapter ${i} ("${c.title}") ends at seq ${c.endSeq}, past the archive ceiling ${archiveCeiling}`);
+        }
+        if (i > 0) {
+            const prev = chapters[i - 1];
+            if (c.startSeq <= prev.startSeq) {
+                throw new Error(`chapter ${i} ("${c.title}") descends: starts ${c.startSeq} after ${prev.startSeq}`);
+            }
+            if (c.startSeq <= prev.endSeq) {
+                throw new Error(`chapter ${i} ("${c.title}") overlaps "${prev.title}": ${c.startSeq}-${prev.endSeq} in both`);
+            }
+        }
+    });
+    return chapters;
+}
+/** Enumerate tool results in a range so the model can decide keep/defer against real sizes. */
+export function toolResultCandidates(events, range) {
+    const out = [];
+    for (const ev of events) {
+        if (ev.type !== 'tool/result' || ev.seq < range.startSeq || ev.seq > range.endSeq)
+            continue;
+        const text = toolResultText(ev.data ?? {});
+        const call = events.find((c) => c.type === 'tool/call' && c.seq < ev.seq && sameCall(c, ev));
+        out.push({
+            seq: ev.seq,
+            toolName: String(call?.data?.name ?? ev.data?.toolName ?? 'tool'),
+            bytes: Buffer.byteLength(text, 'utf8'),
+            estimatedTokens: estimateTokens(text),
+            excerpt: text.slice(0, 160),
+        });
+    }
+    return out;
+}
+function sameCall(call, result) {
+    const callId = call.data?.callId;
+    const message = result.data?.message;
+    const source = message?.source;
+    const resultCallId = source?.callId ?? result.data?.callId;
+    return callId !== undefined && resultCallId !== undefined && String(callId) === String(resultCallId);
+}
+/**
+ * Render one chapter. `overrides` is the model's sparse exception list; anything not named follows the
+ * default rule (small results inline, large ones deferred). Either way the artifact is written, so a wrong
+ * call costs a `read` and never loses data.
+ */
+export function renderChapter(events, range, config, overrides = [], topics = []) {
+    const inline = new Map(overrides.map((o) => [o.seq, o.inline]));
+    // render → redact → write: the single chokepoint, so chapters AND the
+    // deferred artifact files (whose bodies are the redacted text, via
+    // ArtifactRef.content) are covered without caller changes.
+    const redact = (t) => redactText(t, config.redactions ?? DEFAULT_REDACTIONS).text;
+    const inRange = events
+        .filter((e) => e.seq >= range.startSeq && e.seq <= range.endSeq)
+        .sort((a, b) => a.seq - b.seq);
+    const body = [`# ${range.title}`, '', `> ${range.summary}`, ''];
+    const artifacts = [];
+    const unrenderedSeqs = [];
+    let toolCalls = 0;
+    let inlinedCount = 0;
+    let deferredCount = 0;
+    let conversationMessages = 0;
+    for (const ev of inRange) {
+        const data = (ev.data ?? {});
+        switch (ev.type) {
+            case 'user/message': {
+                // The one boundary (src/injections.ts): host-injected context — a
+                // project's own instruction files, runtime snapshots, skill catalogs,
+                // and THIS plugin's TOC notices — is not conversation. Whole injected
+                // events render as a countable marker; injected spans inside human
+                // messages are removed the same way. Originals stay in the session log.
+                const screen = screenConversation(data, textOf(data.content), 'user');
+                if (screen.omittedEvent) {
+                    body.push(omittedMarker(screen.sourceKind, screen.removedChars), '');
+                    break;
+                }
+                if (screen.removedChars > 0)
+                    body.push(omittedMarker('<system-reminder> span(s)', screen.removedChars), '');
+                const text = redact(screen.text);
+                if (text.length === 0) {
+                    if (screen.removedChars === 0)
+                        unrenderedSeqs.push(ev.seq); // a marker above IS a render
+                    break;
+                }
+                conversationMessages += 1;
+                body.push(`**User:**`, '', fenced(text), '');
+                break;
+            }
+            case 'assistant/message': {
+                const message = (data.message ?? data);
+                const asstSpans = stripReminderSpans(textOf(message.content));
+                if (asstSpans.removedChars > 0)
+                    body.push(omittedMarker('<system-reminder> span(s)', asstSpans.removedChars), '');
+                const text = redact(asstSpans.text);
+                const reasoning = redact(stripReminderSpans(blocksOf(message.content)
+                    .filter((b) => b.type === 'reasoning')
+                    .map((b) => b.text ?? '')
+                    .join('\n')).text);
+                let rendered = false;
+                if (reasoning.length > 0) {
+                    body.push('<sub>_reasoning:_</sub>', '', fenced(reasoning), '');
+                    rendered = true;
+                }
+                if (text.length > 0) {
+                    body.push(`**Assistant:**`, '', fenced(text), '');
+                    rendered = true;
+                }
+                if (rendered)
+                    conversationMessages += 1;
+                else if (asstSpans.removedChars === 0)
+                    unrenderedSeqs.push(ev.seq);
+                break;
+            }
+            case 'tool/call': {
+                toolCalls += 1;
+                const name = String(data.name ?? 'unknown');
+                const args = redact(typeof data.arguments === 'string' ? data.arguments : JSON.stringify(data.arguments ?? {}));
+                // Invocations always stay inline: this is the "what was attempted" half of the record.
+                body.push(`- ↳ **${name}** \`${args.slice(0, 400)}\`${args.length > 400 ? ' …' : ''} (seq ${ev.seq})`);
+                break;
+            }
+            case 'tool/result': {
+                const text = redact(toolResultText(data));
+                const tokens = estimateTokens(text);
+                const wantsInline = inline.get(ev.seq) ?? tokens <= config.toolResultDeferFloorTokens;
+                const priorCall = [...inRange].reverse().find((c) => c.type === 'tool/call' && c.seq < ev.seq);
+                const toolName = String(priorCall?.data?.name ?? 'tool');
+                const ref = artifactRef(text, { toolName, sourceSeq: ev.seq, inlined: wantsInline });
+                artifacts.push(ref);
+                if (wantsInline) {
+                    inlinedCount += 1;
+                    body.push(`  - result (seq ${ev.seq}, ${ref.bytes} B, also at \`${ref.path}\`):`, '', fenced(text), '');
+                }
+                else {
+                    deferredCount += 1;
+                    body.push(`  - result: ${ref.bytes} B ≈ ${tokens} tok, \`${ref.sha256.slice(0, 7)}…\` → \`${ref.path}\``);
+                }
+                break;
+            }
+            case 'turn/start':
+            case 'turn/end':
+            case 'step/start':
+            case 'step/end':
+                break; // lifecycle noise: intentionally absent from the body, ranges still recorded in frontmatter
+            default:
+                unrenderedSeqs.push(ev.seq);
+        }
+    }
+    const bodyText = body.join('\n');
+    const estimatedTokens = estimateTokens(bodyText);
+    const frontmatter = [
+        '---',
+        `title: ${JSON.stringify(range.title)}`,
+        `seqRange: [${range.startSeq}, ${range.endSeq}]`,
+        `events: ${inRange.length}`,
+        `tokens: ${estimatedTokens}  # chars/4 estimate`,
+        // The declared anchor MUST hash exactly what parseChapterFile returns as
+        // the body (file = frontmatter + bodyText + '\n' ⇒ parsed body carries the
+        // trailing newline). Hashing bare bodyText made EVERY real chapter fail
+        // the enrich guard's self-consistency check — caught by the enrich e2e
+        // 2026-09-23, invisible for eras behind the host logger.
+        `sha256: ${sha256(`${bodyText}\n`)}`,
+        `topics: [${[...new Set(topics)].map((t) => JSON.stringify(t)).join(', ')}]`,
+        `artifacts: ${artifacts.length}`,
+        `unrenderedSeqs: [${unrenderedSeqs.join(', ')}]`,
+        '---',
+        '',
+    ].join('\n');
+    return {
+        range,
+        topics: [...new Set(topics)],
+        markdown: frontmatter + bodyText + '\n',
+        artifacts,
+        stats: {
+            estimatedTokens,
+            estimatedBytes: Buffer.byteLength(bodyText, 'utf8'),
+            events: inRange.length,
+            messages: conversationMessages,
+            toolCalls,
+            toolResultsInlined: inlinedCount,
+            toolResultsDeferred: deferredCount,
+            overTarget: estimatedTokens > config.chapterTokenTarget,
+            unrenderedSeqs,
+        },
+    };
+}
+/**
+ * The cumulative index that replaces compacted history. Built from registry records, never from an LLM —
+ * which is the entire latency argument: no summarization call, no tokens, no paraphrase.
+ */
+export function renderIndex(entries) {
+    return entries
+        .map((e, i) => `${i + 1}. [${e.title}](${e.path}) — ${e.summary}`)
+        .join('\n');
+}
+//# sourceMappingURL=render.js.map

package/lib/render.js.map

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

package/lib/repo.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Record §2.3, exact: lowercase; strip `https://` / `ssh://`; convert
+ * `user@host:path` → `host/path`; strip trailing `/` and `.git`; KEEP the
+ * host (two hosts, same path = different projects).
+ */
+export declare function canonicalizeRemote(url: string): string;
+/** UUIDv5(NAMESPACE_OID, name) per RFC 4122 — deterministic, name-derived. */
+export declare const NAMESPACE_OID = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
+export declare function uuidv5(namespaceUuid: string, name: string): string;
+/** The project key: stable across machines for the same remote (record §2.3). */
+export declare const projectKeyFromRemote: (url: string) => string;
+/**
+ * A knowledge upstream target string (record §2.1/§3.2 + §15 amendment
+ * "transport is pluggable"). Shapes:
+ *   https://host/org/repo(.git)     git over HTTPS (token required, §2.1)
+ *   /some/dir.git | ./dir | ~dir    local-path git bare pool (no credentials)
+ *   treedx+http(s)://host[:port]/repo-name   TreeDX managed repository
+ * The `treedx+` prefix is the ONLY kind discriminator — identity, credentials,
+ * and the mirror layout are provider-independent beyond it.
+ */
+export interface KnowledgeRemoteTarget {
+    kind: 'git' | 'treedx';
+    /** The raw string as the user typed it (stored as `ProjectRecord.remote`). */
+    raw: string;
+    /** TreeDX: REST base URL + the managed repository name. */
+    treedx?: {
+        baseUrl: string;
+        repoName: string;
+    };
+}
+/** Parse an upstream target. Throws (never guesses) on a treedx+ URL without a
+ * repository name — a wrong identity means syncing into the wrong pool. */
+export declare function parseKnowledgeRemote(target: string): KnowledgeRemoteTarget;
+/**
+ * Project identity for a parsed target (§2.3 unchanged in spirit): for git,
+ * the canonical remote; for TreeDX, `treedx/` + the canonical form of
+ * `baseUrl/repoName`. The prefix keeps transports distinct on purpose —
+ * a server that happens to mirror the same host/port/path as a git remote
+ * is a DIFFERENT pool, and two linked records must never fight over one key.
+ */
+export declare function projectKeyForTarget(t: KnowledgeRemoteTarget): string;
+/**
+ * Parse the minimum of a git config we need: the first remote's url,
+ * preferring `origin`. Comments (# ;), sections, and whitespace handled;
+ * anything exotic returns null rather than guessing.
+ */
+export declare function parseGitConfigRemoteUrl(text: string): string | null;
+export interface ProjectRemote {
+    remote: string;
+    /** `remote` = from a git remote; `path-derived` = non-git workspace fallback. */
+    source: 'remote' | 'path-derived';
+}
+/**
+ * Discover the project's remote WITHOUT a git binary: read `.git` as a file
+ * or directory, parse its `config` (following a `gitdir:` pointer for
+ * worktrees/submodules, relative to `cwd`). Non-git workspace → the
+ * path-derived fallback is the CALLER's choice (this returns null), so the
+ * key's `source` flag stays an explicit decision.
+ */
+export declare function readProjectRemote(cwd: string): ProjectRemote | null;
+/** Resolve the project identity: override > discovered remote > path-derived. */
+export declare function resolveProject(cwd: string, overrideKey?: string, overrideRemote?: string): {
+    projectKey: string;
+    projectKeySource: 'override' | 'remote' | 'path-derived';
+    remote: string | null;
+};
+/** Repo layout (record §2.2) — every path the sync/index/search layers touch. */
+export declare function repoPaths(projectKey: string, harnessId: string, sessionId?: string): {
+    projectYml: string;
+    chaptersDir: string;
+    artifactsDir: string;
+    collectionsFile: (sid: string) => string;
+    indexDir: string;
+    indexManifest: string;
+    curationFile: string;
+    rulesDir: string;
+    vocabularyJson: string;
+};

package/lib/repo.js

@@ -0,0 +1,184 @@
+/**
+ * Project identity and knowledge-repo layout (knowledge-repo.md §2.2–2.3).
+ *
+ * Pure module: no cordis, no network, no git binary. `canonicalizeRemote` +
+ * UUIDv5 give every machine the SAME key for the same project (local paths
+ * differ; the remote is the identity). `.git/config` is parsed as a plain
+ * file — the no-git-executable rule (record §3.2) applies to discovery too.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Record §2.3, exact: lowercase; strip `https://` / `ssh://`; convert
+ * `user@host:path` → `host/path`; strip trailing `/` and `.git`; KEEP the
+ * host (two hosts, same path = different projects).
+ */
+export function canonicalizeRemote(url) {
+    let s = url.trim().toLowerCase();
+    s = s.replace(/^(?:https?|ssh|git|file):\/\//, '');
+    // file:// urls carry no host, only a path
+    s = s.replace(/^\/+/, '');
+    // embedded credentials (https://user:token@host/…) must NOT fork identity:
+    // the same repo pasted with and without creds is the same pool. Colon-bearing
+    // userinfo only ever appears in scheme-form URLs (scp usernames have none).
+    s = s.replace(/^[^@/]*:[^@/]*@/, '');
+    // [user@]host:path (scp-style) and [user@]host/path (scheme-form, after the
+    // scheme strip above)
+    s = s.replace(/^([a-z0-9._-]+)@([a-z0-9.-]+)[:\/](.+)$/, (_m, _user, host, p) => `${host}/${p}`);
+    s = s.replace(/^([a-z0-9.-]+):(.+)$/, (_m, host, p) => `${host}/${p}`);
+    s = s.replace(/\/+$/, '');
+    s = s.replace(/\.git$/, '');
+    return s;
+}
+/** UUIDv5(NAMESPACE_OID, name) per RFC 4122 — deterministic, name-derived. */
+export const NAMESPACE_OID = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';
+export function uuidv5(namespaceUuid, name) {
+    const ns = namespaceUuid.replace(/-/g, '');
+    if (ns.length !== 32)
+        throw new Error(`uuidv5: namespace is not a UUID: ${namespaceUuid}`);
+    const b = createHash('sha1').update(Buffer.concat([Buffer.from(ns, 'hex'), Buffer.from(name, 'utf8')])).digest();
+    b[6] = (b[6] & 0x0f) | 0x50; // version 5
+    b[8] = (b[8] & 0x3f) | 0x80; // variant 10xx
+    // RFC 4122: the first 16 OCTETS of the SHA-1 (not all 20)
+    const h = b.subarray(0, 16).toString('hex');
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+/** The project key: stable across machines for the same remote (record §2.3). */
+export const projectKeyFromRemote = (url) => uuidv5(NAMESPACE_OID, canonicalizeRemote(url));
+const TREEDX_FORM = /^treedx\+(https?:\/\/\S+)$/i;
+/** Parse an upstream target. Throws (never guesses) on a treedx+ URL without a
+ * repository name — a wrong identity means syncing into the wrong pool. */
+export function parseKnowledgeRemote(target) {
+    const raw = target.trim();
+    const m = TREEDX_FORM.exec(raw);
+    if (m === null)
+        return { kind: 'git', raw };
+    let u;
+    try {
+        u = new URL(m[1]);
+    }
+    catch {
+        throw new Error(`treedx+ remote is not a valid URL: ${raw}`);
+    }
+    const segs = u.pathname.split('/').filter((s) => s !== '' && !(s === 'api' && u.pathname.includes('/api/v1')) && s !== 'v1');
+    if (segs.length === 0)
+        throw new Error(`treedx+ remote needs a repository name: treedx+<url>/repo — got ${raw}`);
+    const repoName = segs[segs.length - 1].toLowerCase(); // TreeDX names are canonical lowercase
+    const trimmed = segs.slice(0, -1);
+    const baseUrl = u.origin + (trimmed.length > 0 ? `/${trimmed.join('/')}` : '');
+    return { kind: 'treedx', raw, treedx: { baseUrl, repoName } };
+}
+/**
+ * Project identity for a parsed target (§2.3 unchanged in spirit): for git,
+ * the canonical remote; for TreeDX, `treedx/` + the canonical form of
+ * `baseUrl/repoName`. The prefix keeps transports distinct on purpose —
+ * a server that happens to mirror the same host/port/path as a git remote
+ * is a DIFFERENT pool, and two linked records must never fight over one key.
+ */
+export function projectKeyForTarget(t) {
+    if (t.treedx !== undefined)
+        return uuidv5(NAMESPACE_OID, `treedx/${canonicalizeRemote(`${t.treedx.baseUrl}/${t.treedx.repoName}`)}`);
+    return projectKeyFromRemote(t.raw);
+}
+/**
+ * Parse the minimum of a git config we need: the first remote's url,
+ * preferring `origin`. Comments (# ;), sections, and whitespace handled;
+ * anything exotic returns null rather than guessing.
+ */
+export function parseGitConfigRemoteUrl(text) {
+    let section = null;
+    let originUrl = null;
+    let firstRemoteUrl = null;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#') || line.startsWith(';'))
+            continue;
+        const sectionMatch = /^\[([^\]]+)\]$/.exec(line);
+        if (sectionMatch !== null) {
+            section = sectionMatch[1];
+            continue;
+        }
+        const kv = /^([A-Za-z0-9.]+)\s*=\s*(.+)$/.exec(line);
+        if (kv === null || section === null)
+            continue;
+        if (kv[1].toLowerCase() !== 'url')
+            continue;
+        const value = kv[2].trim().replace(/^["']|["']$/g, '');
+        const sectionName = section.replace(/^remote\s+"?([^"]+)"?$/i, '$1').toLowerCase();
+        if (sectionName === 'origin' && originUrl === null)
+            originUrl = value;
+        else if (/^remote/.test(section) && firstRemoteUrl === null)
+            firstRemoteUrl = value;
+    }
+    return originUrl ?? firstRemoteUrl;
+}
+/**
+ * Discover the project's remote WITHOUT a git binary: read `.git` as a file
+ * or directory, parse its `config` (following a `gitdir:` pointer for
+ * worktrees/submodules, relative to `cwd`). Non-git workspace → the
+ * path-derived fallback is the CALLER's choice (this returns null), so the
+ * key's `source` flag stays an explicit decision.
+ */
+export function readProjectRemote(cwd) {
+    const dotGit = path.join(cwd, '.git');
+    let configPath = null;
+    try {
+        const st = fs.statSync(dotGit);
+        if (st.isDirectory())
+            configPath = path.join(dotGit, 'config');
+        else if (st.isFile()) {
+            const pointer = fs.readFileSync(dotGit, 'utf8').trim();
+            const m = /^gitdir:\s*(.+)$/m.exec(pointer);
+            if (m !== null) {
+                const target = m[1].trim();
+                configPath = path.isAbsolute(target) ? path.join(target, 'config') : path.join(cwd, target, 'config');
+            }
+        }
+    }
+    catch {
+        return null; // no .git, unreadable, or not git
+    }
+    if (configPath === null)
+        return null;
+    try {
+        const url = parseGitConfigRemoteUrl(fs.readFileSync(configPath, 'utf8'));
+        if (url === null)
+            return null;
+        return { remote: url, source: 'remote' };
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve the project identity: override > discovered remote > path-derived. */
+export function resolveProject(cwd, overrideKey, overrideRemote) {
+    if (overrideKey !== undefined && overrideKey !== '') {
+        return { projectKey: overrideKey, projectKeySource: 'override', remote: overrideRemote ?? null };
+    }
+    const discovered = overrideRemote !== undefined && overrideRemote !== ''
+        ? { remote: overrideRemote, source: 'remote' }
+        : readProjectRemote(cwd);
+    if (discovered !== null) {
+        return { projectKey: projectKeyFromRemote(discovered.remote), projectKeySource: discovered.source, remote: discovered.remote };
+    }
+    return { projectKey: uuidv5(NAMESPACE_OID, cwd), projectKeySource: 'path-derived', remote: null };
+}
+/** Repo layout (record §2.2) — every path the sync/index/search layers touch. */
+export function repoPaths(projectKey, harnessId, sessionId) {
+    const base = '';
+    return {
+        projectYml: path.join(base, 'project.yml'),
+        chaptersDir: sessionId === undefined
+            ? path.join(base, 'chapters', projectKey)
+            : path.join(base, 'chapters', projectKey, sessionId),
+        artifactsDir: path.join(base, 'artifacts', projectKey),
+        collectionsFile: (sid) => path.join(base, 'collections', projectKey, `${sid}.jsonl`),
+        indexDir: path.join(base, 'index'),
+        indexManifest: path.join(base, 'index', 'manifest.json'),
+        curationFile: path.join(base, 'edits', harnessId, 'curation.jsonl'),
+        rulesDir: path.join(base, 'rules', projectKey),
+        vocabularyJson: path.join(base, 'topics', 'vocabulary.json'),
+    };
+}
+//# sourceMappingURL=repo.js.map

package/lib/repo.js.map

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

package/lib/rules-commands.d.ts

@@ -0,0 +1,24 @@
+import { type RuleRecord } from './rules.ts';
+import type { ProjectRecord } from './sync.ts';
+export interface RulesIo {
+    cwd(): string;
+    storeRoot: string;
+    harnessId: string;
+    store: {
+        rules(): IterableIterator<[string, RuleRecord]>;
+        getRule(id: string): RuleRecord | undefined;
+        putRule(id: string, value: RuleRecord): Promise<void>;
+    };
+    projectFor(cwd: string): ProjectRecord | undefined;
+    mirrorDir(cwd: string): string;
+    /** arm an immediate sync so facts and files travel (never throws) */
+    syncNow(cwd: string): Promise<void>;
+    /** provenance of the ADD path: 'manual' for commands, the session id for the tool */
+    sourceSession?: string;
+    now: () => Date;
+}
+export interface RulesReply {
+    kind: 'success' | 'error';
+    text: string;
+}
+export declare function rulesCommand(io: RulesIo, args: string): Promise<RulesReply>;