@entelligentsia/forgecli 1.0.20 → 1.0.25

package/dist/extensions/forgecli/transcript-archive-types.js

@@ -0,0 +1,130 @@
+// transcript-archive-types.ts — schemas for the central transcript archive.
+//
+// The archive lives under `~/.pi/forge-cli/transcripts/` (see paths/paths.ts)
+// and mirrors every orchestrator run (run-task / fix-bug / run-sprint task)
+// from project-local `.forge/transcripts/` into a permanent, compressed,
+// cross-project store:
+//
+//   transcripts/
+//     index.jsonl                     ← one IndexEntry line per archived run
+//     projects.json                   ← ProjectsRegistry (projectKey → identity)
+//     <projectKey>/<entityId>/<runId>/
+//         manifest.json               ← RunManifest
+//         orchestrator.jsonl          ← copied as-is (greppable)
+//         <ISO>__<entityId>__<phase>.json.gz
+//
+// Everything read back from disk is untrusted (crash-truncated writes,
+// hand-edits): readers Value.Check before use and return null on mismatch —
+// they never throw on malformed input.
+import { Type } from "typebox";
+/** Per-phase token usage, captured from the subagent transcript header. */
+export const PhaseUsageSchema = Type.Object({
+    input: Type.Number(),
+    output: Type.Number(),
+    cacheRead: Type.Number(),
+    cacheWrite: Type.Number(),
+    cost: Type.Number(),
+    contextTokens: Type.Optional(Type.Number()),
+    turns: Type.Optional(Type.Number()),
+});
+/** One pipeline phase within an archived run. */
+export const PhaseRecordSchema = Type.Object({
+    role: Type.String(),
+    attempt: Type.Number(),
+    /** Verdict from the orchestrator phase-end event; "n/a" when none applies. */
+    verdict: Type.String(),
+    model: Type.Optional(Type.String()),
+    provider: Type.Optional(Type.String()),
+    usage: Type.Optional(PhaseUsageSchema),
+    /** Archived phase-transcript filename (without the .gz suffix). */
+    file: Type.Optional(Type.String()),
+    /**
+     * Archived live tail-log filename (without the .gz suffix) — the exact
+     * lines the dashboard rendered during the run (`*.tail.jsonl`). Replay
+     * prefers this over reconstructing a digest from the transcript.
+     */
+    tailFile: Type.Optional(Type.String()),
+    startedAt: Type.Optional(Type.String()),
+    elapsedMs: Type.Optional(Type.Number()),
+});
+/** Aggregate bucket used for both byModel and byProvider rollups. */
+export const UsageAggregateSchema = Type.Object({
+    input: Type.Number(),
+    output: Type.Number(),
+    cost: Type.Number(),
+    phases: Type.Number(),
+});
+export const RunTotalsSchema = Type.Object({
+    input: Type.Number(),
+    output: Type.Number(),
+    cacheRead: Type.Number(),
+    cacheWrite: Type.Number(),
+    cost: Type.Number(),
+    byModel: Type.Record(Type.String(), UsageAggregateSchema),
+    byProvider: Type.Record(Type.String(), UsageAggregateSchema),
+    /** Count of phase-loopback events (revision loops) in the run. */
+    revisionLoops: Type.Number(),
+});
+export const RunOutcomeSchema = Type.Union([
+    Type.Literal("complete"),
+    Type.Literal("halted"),
+    Type.Literal("cancelled"),
+    Type.Literal("error"),
+    /** No pipeline-end event found — crash- or in-flight-truncated run. */
+    Type.Literal("incomplete"),
+]);
+export const EntityKindSchema = Type.Union([
+    Type.Literal("task"),
+    Type.Literal("bug"),
+    Type.Literal("sprint"),
+    Type.Literal("unknown"),
+]);
+/** manifest.json — full metadata for one archived run. */
+export const RunManifestSchema = Type.Object({
+    schema: Type.Literal("forge-run-manifest/v1"),
+    runId: Type.String(),
+    projectKey: Type.String(),
+    projectPath: Type.String(),
+    projectName: Type.String(),
+    projectPrefix: Type.String(),
+    entityId: Type.String(),
+    entityKind: EntityKindSchema,
+    /** Back-reference for sprint-nested task runs — no synthetic sprint container. */
+    sprintId: Type.Optional(Type.String()),
+    startedAt: Type.String(),
+    finishedAt: Type.Optional(Type.String()),
+    durationMs: Type.Optional(Type.Number()),
+    outcome: RunOutcomeSchema,
+    phases: Type.Array(PhaseRecordSchema),
+    totals: RunTotalsSchema,
+    archivedAt: Type.String(),
+});
+/** One line of index.jsonl — the append-only global run timeline. */
+export const IndexEntrySchema = Type.Object({
+    runId: Type.String(),
+    projectKey: Type.String(),
+    entityId: Type.String(),
+    entityKind: EntityKindSchema,
+    sprintId: Type.Optional(Type.String()),
+    startedAt: Type.String(),
+    outcome: RunOutcomeSchema,
+    input: Type.Number(),
+    output: Type.Number(),
+    cost: Type.Number(),
+    durationMs: Type.Optional(Type.Number()),
+    archivedAt: Type.String(),
+});
+const ProjectEntrySchema = Type.Object({
+    path: Type.String(),
+    prefix: Type.String(),
+    name: Type.String(),
+    firstSeen: Type.String(),
+    lastSeen: Type.String(),
+    runCount: Type.Number(),
+});
+/** projects.json — projectKey → identity registry. */
+export const ProjectsRegistrySchema = Type.Object({
+    version: Type.Literal(1),
+    projects: Type.Record(Type.String(), ProjectEntrySchema),
+});
+//# sourceMappingURL=transcript-archive-types.js.map

package/dist/extensions/forgecli/transcript-archive-types.js.map

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

package/dist/extensions/forgecli/transcript-archive.d.ts

@@ -0,0 +1,127 @@
+import { getTranscriptArchiveRoot } from "./paths/paths.js";
+import { type IndexEntry, type ProjectsRegistry, type RunManifest } from "./transcript-archive-types.js";
+export interface ProjectIdentity {
+    prefix: string;
+    name: string;
+    projectDir: string;
+}
+/**
+ * Read `{prefix, name, projectDir}` from a `.forge/config.json`. Defaults on
+ * any failure (missing file, malformed JSON, absent fields) — never throws.
+ * `projectDir` is derived from the config path itself (`<dir>/.forge/config.json`).
+ */
+export declare function readProjectIdentity(configPath: string): ProjectIdentity;
+/**
+ * `<prefix>-<sha256(realpath(projectDir)).slice(0,8)>` — prefix alone can
+ * collide across projects (two repos both named "FORGE"); the path hash
+ * disambiguates. Falls back to the raw path when realpath throws (deleted
+ * or unmounted project dir — archive entries must remain addressable).
+ */
+export declare function computeProjectKey(projectDir: string, prefix: string): string;
+interface PhaseFileInfo {
+    /** Absolute path to the project-local phase transcript JSON. */
+    absPath: string;
+    /** Basename, e.g. "20260601T100100Z__CART-BUG-001__triage.json". */
+    file: string;
+    /** Compact ISO prefix from the filename. */
+    ts: string;
+    /** Role segment from the filename (third "__" part onward). */
+    role: string;
+}
+/** One discovered run: source files + the manifest built from them. */
+export interface DiscoveredRun {
+    runId: string;
+    jsonlPath: string;
+    phaseFiles: PhaseFileInfo[];
+    /** Live tail-view logs (`*.tail.jsonl`) belonging to this run. */
+    tailFiles: PhaseFileInfo[];
+    manifest: RunManifest;
+}
+interface BuildOptions {
+    /** Sprint back-reference stamped onto the manifest (run-sprint wiring). */
+    sprintId?: string;
+}
+/**
+ * Discover every run in a project-local entity transcript dir
+ * (`.forge/transcripts/<entityId>/`) and build a RunManifest for each.
+ *
+ * A "run" is one orchestrator JSONL file; its runId is the compact-ISO
+ * pipeline-start timestamp (falling back to the filename prefix). Phase
+ * transcript files are assigned to the latest run whose start precedes
+ * them — compact ISO prefixes compare lexicographically as timestamps.
+ */
+export declare function buildRunsForEntityDir(entityDir: string, identity: ProjectIdentity, projectKey: string, opts?: BuildOptions): DiscoveredRun[];
+export interface ArchiveRunResult {
+    archived: boolean;
+    runDir?: string;
+    error?: string;
+}
+export interface ArchiveRunOptions {
+    /** Project dir (the dir containing `.forge/`). */
+    cwd: string;
+    /** Project-local orchestrator JSONL path for the run to archive. */
+    orchestratorJsonlPath: string;
+    /** Sprint back-reference for sprint-nested task runs. */
+    sprintId?: string;
+    /** Override for `<cwd>/.forge/config.json` (tests). */
+    configPath?: string;
+}
+/**
+ * Archive the run identified by its project-local orchestrator transcript.
+ * Called by orchestrators after the pipeline result is known. Best-effort,
+ * never throws.
+ */
+export declare function archiveRun(opts: ArchiveRunOptions): ArchiveRunResult;
+export interface SweepResult {
+    adopted: number;
+    errors: number;
+}
+/**
+ * Adopt orphans: archive every project-local run whose runId isn't in the
+ * central index. Covers crash recovery (pipeline died before its archive
+ * call) and adoption of pre-existing history (transcripts written before
+ * this feature shipped). Called best-effort at pipeline start; never throws.
+ */
+export declare function sweepProjectTranscripts(cwd: string, configPath?: string): SweepResult;
+/** Read index.jsonl — skips malformed/truncated lines, never throws. */
+export declare function readIndex(): IndexEntry[];
+/** Read projects.json — empty registry on any failure, never throws. */
+export declare function readProjects(): ProjectsRegistry;
+/** Read `<runDir>/manifest.json` — null on missing/truncated/mismatched. */
+export declare function readManifest(runDir: string): RunManifest | null;
+/**
+ * Gunzip + parse an archived phase transcript. `file` is the manifest's
+ * phase `file` field (without `.gz`). Null on any failure, never throws.
+ */
+export declare function gunzipPhase(runDir: string, file: string): Record<string, unknown> | null;
+/** One persisted live tail-view line (see viewport/events.ts TailLogEntry). */
+export interface ArchivedTailEntry {
+    line: string;
+    warning?: boolean;
+}
+/**
+ * Gunzip + parse an archived live tail log (`*.tail.jsonl.gz`). Returns the
+ * exact lines the dashboard rendered during the run, in order. Tolerant of
+ * truncated tails; null when the file is missing/unreadable. Never throws.
+ */
+export declare function gunzipTailLog(runDir: string, file: string): ArchivedTailEntry[] | null;
+/** Resolve the archive dir for an index entry. */
+export declare function runDirForEntry(entry: IndexEntry): string;
+/**
+ * Per-turn digest of a gunzipped phase payload — never a raw JSON dump.
+ * Each assistant message is a turn: first text line + tool-call names;
+ * toolResult messages render as compact result markers.
+ */
+export declare function digestPhasePayload(payload: Record<string, unknown>): string[];
+/**
+ * VERBOSE digest of a gunzipped phase payload — the replay-dashboard feed.
+ * Unlike digestPhasePayload (compact markers for the `show` table), this
+ * carries the actual transcript content so a replayed run is readable:
+ * full assistant text (capped per turn), thinking first-lines, tool-call
+ * argument previews, and tool-result first-line previews.
+ *
+ * Multi-line assistant text is pushed as ONE entry — the dashboard splits
+ * lines at display time, and the tree's per-entry char cap still applies.
+ */
+export declare function digestPhasePayloadVerbose(payload: Record<string, unknown>): string[];
+export { getTranscriptArchiveRoot };