looply-cli 0.0.0-stage → 0.2.0

package/dist/scan-events.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCAN_LANE = void 0;
+exports.newScanId = newScanId;
+exports.scanStartedEvent = scanStartedEvent;
+exports.lensResultEvent = lensResultEvent;
+exports.scanFinishedEvents = scanFinishedEvents;
+const core_1 = require("@looply/core");
+/**
+ * The events a scan writes.
+ *
+ * A scan is the longest thing looply does that produces nothing until it is
+ * finished: six read-only agent passes, twenty minutes, and — until now — not a
+ * single line in the ledger. From the phone that is indistinguishable from a
+ * machine that has stopped answering, which is the worst way for a working
+ * system to look.
+ *
+ * The builders are pure and the ledger is passed in, so what a scan reports is
+ * testable without a filesystem, an agent or a server.
+ */
+/**
+ * Every event carries a `runId`, and a scan is not a run — but the lane is a
+ * free string, so it is what says which this is. A scan mints a run-shaped id
+ * (the server keys events on it and will create a row for it either way) and
+ * marks the lane, so the app can tell the two apart without a schema change.
+ */
+exports.SCAN_LANE = 'scan';
+/** Not `runner`: no round ran, and attributing a scan to the runner would make
+ * the run report count work that never happened. */
+const SCAN_ACTOR = 'system';
+function newScanId(now) {
+    return (0, core_1.newId)('run', now);
+}
+function event(ctx, kind, data) {
+    return {
+        ts: new Date(ctx.now()).toISOString(),
+        runId: ctx.scanId,
+        projectId: ctx.projectId,
+        lane: exports.SCAN_LANE,
+        actor: SCAN_ACTOR,
+        kind,
+        data,
+    };
+}
+/** Written before the first pass, so the phone knows what it is waiting for. */
+function scanStartedEvent(lensKeys, ctx) {
+    return event(ctx, 'scan.started', { lenses: [...lensKeys] });
+}
+/**
+ * One pass finished.
+ *
+ * There is no per-lens kind in the schema, and the only kind that carries free
+ * text is `alert` — so this is an alert, at `info` when the pass worked. Waiting
+ * for `scan.finished` instead would mean the phone shows nothing at all for the
+ * length of the scan, which is the thing being fixed. A pass that produced
+ * nothing usable is a genuine `warn`: it means a sixth of the scan was wasted
+ * and the reason is worth reading now rather than after the whole scan.
+ */
+function lensResultEvent(result, label, ctx) {
+    if (!result.ok) {
+        return event(ctx, 'alert', {
+            code: 'scan-lens-failed',
+            severity: 'warn',
+            text: `${label}: nothing usable — ${result.reason ?? 'unknown'}`,
+        });
+    }
+    const over = result.overflow ? `, ${result.overflow} past the cap and cut` : '';
+    return event(ctx, 'alert', {
+        code: 'scan-lens',
+        severity: 'info',
+        text: `${label}: ${result.findings.length} found${over}`,
+    });
+}
+/**
+ * What the scan produced, in the order it happened: the items first, then the
+ * summary. An `item.created` for something the queue does not hold would send
+ * the phone to an item that is not there, so callers emit these only after the
+ * queue write, and only for the items that were actually inserted.
+ */
+function scanFinishedEvents(report, ctx) {
+    const events = report.items.map((item) => event(ctx, 'item.created', {
+        itemId: item.id,
+        title: item.title,
+        tag: item.tag,
+        source: item.source,
+        evidence: item.evidence,
+    }));
+    events.push(event(ctx, 'scan.finished', { found: report.found, byLens: report.byLens }));
+    return events;
+}
+//# sourceMappingURL=scan-events.js.map

package/dist/scan-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-events.js","sourceRoot":"","sources":["../src/scan-events.ts"],"names":[],"mappings":";;;AAqCA,8BAEC;AAmBD,4CAEC;AAYD,0CAkBC;AAQD,gDAYC;AA9GD,uCAAiF;AAIjF;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACU,QAAA,SAAS,GAAG,MAAM,CAAC;AAEhC;oDACoD;AACpD,MAAM,UAAU,GAAU,QAAQ,CAAC;AAUnC,SAAgB,SAAS,CAAC,GAAY;IACpC,OAAO,IAAA,YAAK,EAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,KAAK,CACZ,GAAqB,EACrB,IAAO,EACP,IAAkB;IAElB,OAAO;QACL,EAAE,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE;QACrC,KAAK,EAAE,GAAG,CAAC,MAAM;QACjB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,IAAI,EAAE,iBAAS;QACf,KAAK,EAAE,UAAU;QACjB,IAAI;QACJ,IAAI;KACY,CAAC;AACrB,CAAC;AAED,gFAAgF;AAChF,SAAgB,gBAAgB,CAAC,QAA2B,EAAE,GAAqB;IACjF,OAAO,KAAK,CAAC,GAAG,EAAE,cAAc,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,eAAe,CAC7B,MAAkB,EAClB,KAAa,EACb,GAAqB;IAErB,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE;YACzB,IAAI,EAAE,kBAAkB;YACxB,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,GAAG,KAAK,sBAAsB,MAAM,CAAC,MAAM,IAAI,SAAS,EAAE;SACjE,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,QAAQ,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,OAAO,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE;QACzB,IAAI,EAAE,WAAW;QACjB,QAAQ,EAAE,MAAM;QAChB,IAAI,EAAE,GAAG,KAAK,KAAK,MAAM,CAAC,QAAQ,CAAC,MAAM,SAAS,IAAI,EAAE;KACzD,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,MAAkB,EAAE,GAAqB;IAC1E,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACvC,KAAK,CAAC,GAAG,EAAE,cAAc,EAAE;QACzB,MAAM,EAAE,IAAI,CAAC,EAAE;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAC,CACH,CAAC;IACF,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,eAAe,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACzF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/scan.d.ts

@@ -0,0 +1,191 @@
+import { type Evidence, type Item } from '@looply/core';
+import type { CommandResult } from './gate';
+/**
+ * `looply scan` — seeding the queue.
+ *
+ * This is the highest-leverage part of the whole system and the least
+ * automatable. The queue that carried the previous harness for thirty-nine
+ * rounds came from a human-directed review, and that is a very high bar. What
+ * makes an automated pass approach it is *lenses*: several read-only passes that
+ * each look for one kind of defect, rather than one pass told to "find problems"
+ * — which reliably returns whatever is cheapest to grep for.
+ *
+ * The output is deliberately over-produced and then trimmed. A lens that returns
+ * eight variants of the same chore has told us something about the lens, not
+ * about the codebase.
+ */
+export interface Lens {
+    key: string;
+    /** One sentence, in the words the app shows while the pass runs. */
+    label: string;
+    /** What this lens is looking for, and — as importantly — what it is not. */
+    brief: string;
+}
+/**
+ * The default lenses.
+ *
+ * Each is narrow on purpose. "Find bugs" produces a list of whatever the model
+ * noticed first; "find places where a failure is swallowed" produces a list you
+ * can act on, and a different one from every other lens.
+ */
+export declare const DEFAULT_LENSES: readonly Lens[];
+/** What a lens is asked to return, per finding. */
+export interface ScanFinding {
+    title: string;
+    tag: string;
+    evidence: Evidence[];
+    /** The lens that produced it — kept so a noisy lens is identifiable. */
+    lens: string;
+}
+export interface ScanInvocation {
+    prompt: string;
+    timeoutMs: number;
+}
+export type ScanInvoke = (prompt: string, timeoutMs: number) => Promise<CommandResult>;
+export interface ScanContext {
+    projectName: string;
+    /** Where the loop is allowed to work; a finding outside it is not actionable. */
+    scope: readonly string[];
+    /** Paths the loop may never touch; findings here are worth having but are blocked. */
+    rails: readonly string[];
+    perLens: number;
+    /**
+     * Where the agent must write its findings.
+     *
+     * Asking for JSON on stdout does not work reliably. Three separate promptings
+     * — task-first, contract-first, "a report is discarded unread" — all produced
+     * a well-written prose review instead, and one produced
+     * `{"reply":"Ready — what would you like me to do?"}` because the format
+     * instruction read as configuration rather than as a task.
+     *
+     * A file is unambiguous. Writing it is a tool call the agent either made or
+     * did not, and whatever it says in the transcript alongside stops mattering.
+     */
+    outputPath: string;
+}
+/**
+ * The lens prompt.
+ *
+ * Shaped by a real failure: an earlier version opened with "You are a read-only
+ * reviewer" and the agent replied by describing the repository and asking which
+ * target to review. A non-interactive agent given a role and no imperative will
+ * orient itself and wait. So this opens with the task, forbids questions
+ * explicitly, and states the output contract twice — once as the instruction and
+ * once as the last thing read.
+ */
+export declare function buildScanPrompt(lens: Lens, ctx: ScanContext): string;
+/**
+ * The follow-up call: prose in, JSON out.
+ *
+ * Every attempt to make a single call both *review the code* and *obey a
+ * format* has failed the same way — the review arrives, well written, as prose,
+ * and the contract is treated as background. The one thing that never failed is
+ * the reviewing itself. So this splits the two: the first call may answer
+ * however it likes, and a second call that reads no code and makes no judgement
+ * turns what it said into the shape.
+ *
+ * It is deliberately not a reviewer. "Do not read any code" is stated because a
+ * call that can open files will start reviewing again, and then it is the same
+ * unreliable single call with an extra bill attached.
+ */
+export declare function buildDistillPrompt(prose: string, lens: Lens, ctx: ScanContext): string;
+export interface ScanExtract {
+    ok: boolean;
+    findings: ScanFinding[];
+    reason?: string;
+}
+/**
+ * Pull the findings out of a transcript.
+ *
+ * Scans from the end: an agent may echo the example object from its own prompt
+ * before producing the real one, and taking the first match would read the
+ * example back as data.
+ */
+export declare function extractFindings(transcript: string, lens: string): ScanExtract;
+export interface LensResult {
+    lens: string;
+    findings: ScanFinding[];
+    ok: boolean;
+    reason?: string;
+    ms: number;
+    /** Findings past `perLens` that were cut. Reported, never silently dropped. */
+    overflow?: number;
+    /**
+     * The tail of what the agent actually said, kept only when the pass failed.
+     *
+     * "Produced nothing usable" is unactionable on its own — the difference
+     * between a timeout, a refusal, and an agent that answered in prose is the
+     * whole diagnosis, and it is invisible unless the transcript survives.
+     */
+    transcriptTail?: string;
+    /**
+     * The findings came from the follow-up call, not the pass itself.
+     *
+     * Worth reporting rather than hiding: this lens cost two agent calls, and a
+     * scan where every lens needs the follow-up is telling us the first prompt is
+     * the thing to fix.
+     */
+    distilled?: true;
+}
+/**
+ * How long the follow-up gets. Much shorter than a lens pass on purpose — it
+ * opens no files and searches nothing, so a follow-up that runs for minutes is
+ * one that started reviewing again, and killing it is the right answer.
+ */
+export declare const DISTILL_TIMEOUT_MS = 90000;
+/** Reads the file the agent was asked to write. Absent is normal, not an error. */
+export type ReadOutput = (path: string) => string | null;
+export declare function runLens(invoke: ScanInvoke, lens: Lens, ctx: ScanContext, timeoutMs: number, readOutput?: ReadOutput): Promise<LensResult>;
+export interface ScanReport {
+    found: number;
+    kept: number;
+    dropped: number;
+    byLens: Record<string, number>;
+    /** Lenses that ran to the end and honestly had nothing to report. */
+    quiet: string[];
+    /**
+     * Lenses that never produced a usable answer at all — a timeout, a crash, or
+     * a review the extractor could not read.
+     *
+     * Kept apart from {@link quiet} because the two are opposites dressed as the
+     * same zero: one is evidence the code is fine, the other is evidence of
+     * nothing whatsoever.
+     */
+    failed: string[];
+    /** Distinct shapes across everything kept. Low means the scan is repeating itself. */
+    entropy: number;
+    items: Omit<Item, 'version'>[];
+}
+/**
+ * Merge every lens's output into a queue-ready batch.
+ *
+ * Two trims, both deliberate. Duplicates across lenses collapse by evidence
+ * location, because two lenses noticing the same line is agreement, not two
+ * pieces of work. Then the shape cap applies, because a batch dominated by one
+ * kind of chore is how a queue decays into busywork.
+ */
+export declare function mergeFindings(results: readonly LensResult[], opts: {
+    projectId: string;
+    maxSameShape: number;
+    now?: number;
+}): ScanReport;
+/**
+ * What a scan that queued nothing actually means.
+ *
+ * `found : 0` was printed for two opposite outcomes: a codebase with nothing
+ * worth queueing, and a scan where no pass came back with an answer anything
+ * could read. The second is the common case today — the agent reviews the code
+ * competently and then answers in prose, and the extractor gets nothing — and
+ * printing it as a zero tells somebody their code is clean when in fact nothing
+ * ever reported on it. Name which one it was, and say what to do instead.
+ *
+ * `looply queue` is deliberately not the pointer here: it is listed under "not
+ * built yet" in the CLI's own usage, and sending someone to a command that does
+ * not exist is the same lie in a different place.
+ *
+ * Empty when the scan queued something — this block is only for a zero.
+ */
+export declare function describeEmptyScan(report: Pick<ScanReport, 'kept' | 'quiet' | 'failed'>): string[];
+/** A human-readable summary for the terminal and for the app's scan card. */
+export declare function renderScanReport(report: ScanReport): string;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.d.ts.map

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