@stevenvincentone/intidev-agentloops 0.1.0

package/dist/storage.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePostgresUrl = resolvePostgresUrl;
+exports.resolveBackend = resolveBackend;
+const backend_1 = require("./backend");
+const postgres_1 = require("./postgres");
+/** Connection string precedence: explicit arg → `DATABASE_URL` env → config. */
+function resolvePostgresUrl(options) {
+    return options.databaseUrl ?? process.env.DATABASE_URL ?? options.config.storage?.databaseUrl;
+}
+/**
+ * Pick a `StateBackend` for the CLI/MCP: Postgres when a connection string is
+ * configured, otherwise the filesystem. `pg` is loaded lazily and is an optional
+ * peer dependency — filesystem users never need it.
+ */
+async function resolveBackend(options) {
+    const url = resolvePostgresUrl(options);
+    if (!url) {
+        return {
+            backend: new backend_1.FilesystemStateBackend(options.cwd),
+            kind: "filesystem",
+            dispose: async () => { },
+        };
+    }
+    const { client, end } = await connectPostgres(url);
+    return { backend: new postgres_1.PostgresStateBackend(client), kind: "postgres", dispose: end };
+}
+async function connectPostgres(connectionString) {
+    let mod;
+    try {
+        mod = await import("pg");
+    }
+    catch {
+        throw new Error("Postgres backend selected (DATABASE_URL or storage.databaseUrl is set) but the 'pg' package is not installed. Install it with: npm install pg");
+    }
+    const pool = new mod.Pool({ connectionString });
+    return { client: pool, end: () => pool.end() };
+}
+//# sourceMappingURL=storage.js.map

package/dist/store.d.ts

@@ -0,0 +1,60 @@
+import { CreateTicketInput, GuardStatus, LoopState, NoteType, Pattern, PatternStatus, ProjectConfig, ResolveInput, Ticket, TicketRedactor, TicketStatus } from "./types";
+import { StateBackend } from "./backend";
+import { SourceConvergenceOptions, SourceConvergenceReport } from "./convergence";
+import { GuardGapOptions, GuardGapReport } from "./guards";
+import { KnowledgeSearchOptions, ResolutionKnowledgeReport, KnowledgeGapsOptions, KnowledgeGapsReport } from "./knowledge";
+import { PriorArtOptions, PriorArtReport } from "./prior-art";
+export declare class AgentLoopStore {
+    private readonly config;
+    private state;
+    private readonly backend;
+    private readonly redactor;
+    constructor(cwd: string, config: ProjectConfig, options?: {
+        redactor?: TicketRedactor;
+        backend?: StateBackend;
+    });
+    private redact;
+    ensureInitialized(project?: string): Promise<LoopState>;
+    createTicket(input: CreateTicketInput): Promise<Ticket>;
+    listTickets(opts: {
+        status?: TicketStatus | "all";
+        kind?: string;
+    }): Promise<Ticket[]>;
+    listPatterns(opts: {
+        status?: PatternStatus | "all";
+    }): Promise<Pattern[]>;
+    getTicketByAnyId(rawId: string): Promise<Ticket | undefined>;
+    showTicket(rawId: string): Promise<Ticket | undefined>;
+    beginTicket(rawId: string): Promise<Ticket>;
+    resolveTicket(input: ResolveInput): Promise<Ticket>;
+    reopenTicket(rawId: string, reason: string): Promise<Ticket>;
+    deferTicket(rawId: string, reason?: string): Promise<Ticket>;
+    addTicketNote(rawId: string, type: NoteType, body: string, author?: string): Promise<Ticket>;
+    setGuard(rawId: string, status: GuardStatus, summary?: string): Promise<Ticket>;
+    private noteCtx;
+    resolvePattern(patternId: string, note: string): Promise<Pattern>;
+    summary(): Promise<{
+        project: string;
+        totalTickets: number;
+        activeTickets: number;
+        triagedTickets: number;
+        resolvedTickets: number;
+        reopenedTickets: number;
+        deferredTickets: number;
+        openPatterns: number;
+        stalledPatterns: number;
+        resolvedPatterns: number;
+    }>;
+    getPattern(id: string): Promise<Pattern | undefined>;
+    getConfig(): ProjectConfig;
+    sourceConvergence(options?: SourceConvergenceOptions): Promise<SourceConvergenceReport>;
+    guardGaps(options?: GuardGapOptions): Promise<GuardGapReport>;
+    searchKnowledge(options?: KnowledgeSearchOptions): Promise<ResolutionKnowledgeReport>;
+    knowledgeGaps(options?: KnowledgeGapsOptions): Promise<KnowledgeGapsReport>;
+    related(rawId: string, options?: PriorArtOptions): Promise<PriorArtReport>;
+    private transitionTicket;
+    private attachPattern;
+    private persist;
+    private get nowState();
+}
+export declare function normalizeTicketInput(raw: string, tickets: Ticket[]): string;

package/dist/store.js

@@ -0,0 +1,339 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentLoopStore = void 0;
+exports.normalizeTicketInput = normalizeTicketInput;
+const config_1 = require("./config");
+const redaction_1 = require("./redaction");
+const backend_1 = require("./backend");
+const aliases_1 = require("./aliases");
+const convergence_1 = require("./convergence");
+const guards_1 = require("./guards");
+const knowledge_1 = require("./knowledge");
+const prior_art_1 = require("./prior-art");
+const SEQ_PAD = 6;
+function ticketId(seq) {
+    return `ISSUE-${String(seq).padStart(SEQ_PAD, "0")}`;
+}
+function patternId(seq) {
+    return `PATTERN-${String(seq).padStart(SEQ_PAD, "0")}`;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+class AgentLoopStore {
+    config;
+    state = null;
+    backend;
+    redactor;
+    constructor(cwd, config, options = {}) {
+        this.config = config;
+        this.backend = options.backend ?? new backend_1.FilesystemStateBackend(cwd);
+        this.redactor = (0, redaction_1.resolveRedactor)(config, options.redactor);
+    }
+    redact(value, context) {
+        return this.redactor.redactText(value, context);
+    }
+    async ensureInitialized(project = this.config.projectName) {
+        if (this.state) {
+            return this.state;
+        }
+        const loaded = await this.backend.load();
+        if (!loaded) {
+            this.state = {
+                version: 1,
+                project,
+                createdAt: nowIso(),
+                updatedAt: nowIso(),
+                nextTicketSeq: 0,
+                nextPatternSeq: 0,
+                tickets: [],
+                patterns: [],
+            };
+            await this.persist();
+            return this.state;
+        }
+        this.state = loaded;
+        if (!this.state.project) {
+            this.state.project = project;
+        }
+        return this.state;
+    }
+    async createTicket(input) {
+        const state = await this.ensureInitialized();
+        const { title, summary, family, kind, source, severity, confidence, tags = [], handoffText } = input;
+        const missing = (0, config_1.requiredFields)(this.config, kind).filter((field) => !input[field]);
+        if (missing.length > 0) {
+            throw new Error(`Missing required fields for ${kind}: ${missing.join(", ")}`);
+        }
+        const id = ticketId(++state.nextTicketSeq);
+        const defaultKindConfig = this.config.ticketKinds.find((entry) => entry.kind === kind);
+        const defaults = defaultKindConfig?.defaultSeverity ?? "medium";
+        const c = this.nowState;
+        const aliases = (0, aliases_1.deriveAliases)({ kind, source }, state.nextTicketSeq, this.config);
+        const ctx = (field) => ({ field, ticketKind: kind, source });
+        const ticket = {
+            id,
+            family,
+            kind,
+            source,
+            title: this.redact(title, ctx("title")),
+            summary: this.redact(summary, ctx("summary")),
+            severity: severity ?? defaults,
+            confidence: confidence ?? "medium",
+            status: "triaged",
+            createdAt: c,
+            updatedAt: c,
+            aliases: Array.from(new Set(aliases)),
+            tags: Array.from(new Set(tags)),
+            notes: [],
+            handoffText: handoffText ? this.redact(handoffText, ctx("handoffText")) : undefined,
+            reproducible: true,
+        };
+        ticket.patternId = this.attachPattern(state, family, ticket.id);
+        state.tickets.push(ticket);
+        state.updatedAt = nowIso();
+        await this.persist();
+        return ticket;
+    }
+    async listTickets(opts) {
+        const state = await this.ensureInitialized();
+        let rows = [...state.tickets];
+        if (opts.status && opts.status !== "all") {
+            rows = rows.filter((ticket) => ticket.status === opts.status);
+        }
+        if (opts.kind) {
+            rows = rows.filter((ticket) => ticket.kind === opts.kind);
+        }
+        return rows.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    }
+    async listPatterns(opts) {
+        const state = await this.ensureInitialized();
+        const rows = [...state.patterns];
+        if (opts.status && opts.status !== "all") {
+            return rows.filter((pattern) => pattern.status === opts.status).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        }
+        return rows.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    }
+    async getTicketByAnyId(rawId) {
+        const state = await this.ensureInitialized();
+        const normalized = normalizeTicketInput(rawId, state.tickets);
+        return state.tickets.find((ticket) => ticket.id === normalized);
+    }
+    async showTicket(rawId) {
+        return this.getTicketByAnyId(rawId);
+    }
+    async beginTicket(rawId) {
+        const ticket = await this.transitionTicket(rawId, "active");
+        ticket.startedAt = nowIso();
+        await this.persist();
+        return ticket;
+    }
+    async resolveTicket(input) {
+        const ticket = await this.transitionTicket(input.id, "resolved");
+        const ctx = (field) => ({
+            field,
+            ticketKind: ticket.kind,
+            source: ticket.source,
+        });
+        ticket.resolutionSummary = this.redact(input.summary, ctx("resolutionSummary"));
+        ticket.verification = input.verification
+            ? this.redact(input.verification, ctx("verification"))
+            : undefined;
+        ticket.resolvedAt = nowIso();
+        ticket.guardStatus = input.guardStatus ?? "none";
+        ticket.guardSummary = input.guardSummary
+            ? this.redact(input.guardSummary, ctx("guardSummary"))
+            : undefined;
+        await this.persist();
+        return ticket;
+    }
+    async reopenTicket(rawId, reason) {
+        const ticket = await this.transitionTicket(rawId, "reopened");
+        ticket.notes.push({
+            id: `${ticket.id}-note-${Date.now()}`,
+            type: "hypothesis",
+            body: `Reopened: ${this.redact(reason, this.noteCtx(ticket))}`,
+            createdAt: nowIso(),
+        });
+        ticket.updatedAt = nowIso();
+        await this.persist();
+        return ticket;
+    }
+    async deferTicket(rawId, reason) {
+        const ticket = await this.transitionTicket(rawId, "deferred");
+        if (reason) {
+            ticket.notes.push({
+                id: `${ticket.id}-note-${Date.now()}`,
+                type: "triage",
+                body: `Deferred: ${this.redact(reason, this.noteCtx(ticket))}`,
+                createdAt: nowIso(),
+            });
+        }
+        ticket.updatedAt = nowIso();
+        await this.persist();
+        return ticket;
+    }
+    async addTicketNote(rawId, type, body, author) {
+        const ticket = await this.transitionTicket(rawId, undefined);
+        ticket.notes.push({
+            id: `${ticket.id}-note-${Date.now()}`,
+            type,
+            body: this.redact(body, this.noteCtx(ticket)),
+            author,
+            createdAt: nowIso(),
+        });
+        ticket.updatedAt = nowIso();
+        await this.persist();
+        return ticket;
+    }
+    async setGuard(rawId, status, summary) {
+        const ticket = await this.transitionTicket(rawId, undefined);
+        ticket.guardStatus = status;
+        ticket.guardSummary = summary
+            ? this.redact(summary, { field: "guardSummary", ticketKind: ticket.kind, source: ticket.source })
+            : undefined;
+        await this.persist();
+        return ticket;
+    }
+    noteCtx(ticket) {
+        return { field: "note", ticketKind: ticket.kind, source: ticket.source };
+    }
+    async resolvePattern(patternId, note) {
+        const state = await this.ensureInitialized();
+        const pattern = state.patterns.find((entry) => entry.id === patternId);
+        if (!pattern) {
+            throw new Error(`Pattern not found: ${patternId}`);
+        }
+        if (pattern.status !== "resolved") {
+            pattern.status = "resolved";
+            pattern.updatedAt = nowIso();
+            if (note) {
+                pattern.title = `${pattern.title} (resolved: ${note})`;
+            }
+        }
+        state.updatedAt = nowIso();
+        await this.persist();
+        return pattern;
+    }
+    async summary() {
+        const state = await this.ensureInitialized();
+        return {
+            project: state.project,
+            totalTickets: state.tickets.length,
+            activeTickets: state.tickets.filter((t) => t.status === "active").length,
+            triagedTickets: state.tickets.filter((t) => t.status === "triaged").length,
+            resolvedTickets: state.tickets.filter((t) => t.status === "resolved").length,
+            reopenedTickets: state.tickets.filter((t) => t.status === "reopened").length,
+            deferredTickets: state.tickets.filter((t) => t.status === "deferred").length,
+            openPatterns: state.patterns.filter((p) => p.status === "active").length,
+            stalledPatterns: state.patterns.filter((p) => p.status === "open").length,
+            resolvedPatterns: state.patterns.filter((p) => p.status === "resolved").length,
+        };
+    }
+    async getPattern(id) {
+        const state = await this.ensureInitialized();
+        return state.patterns.find((entry) => entry.id === id);
+    }
+    getConfig() {
+        return this.config;
+    }
+    async sourceConvergence(options = {}) {
+        const state = await this.ensureInitialized();
+        return (0, convergence_1.sourceConvergenceReport)(state.tickets, state.patterns, options);
+    }
+    async guardGaps(options = {}) {
+        const state = await this.ensureInitialized();
+        return (0, guards_1.guardGapReport)(state.tickets, this.config, options);
+    }
+    async searchKnowledge(options = {}) {
+        const state = await this.ensureInitialized();
+        return (0, knowledge_1.resolutionKnowledge)(state.tickets, options);
+    }
+    async knowledgeGaps(options = {}) {
+        const state = await this.ensureInitialized();
+        return (0, knowledge_1.knowledgeGaps)(state.tickets, options);
+    }
+    async related(rawId, options = {}) {
+        const state = await this.ensureInitialized();
+        const targetId = normalizeTicketInput(rawId, state.tickets);
+        const configured = this.config.priorArt;
+        return (0, prior_art_1.relatedTickets)(targetId, state.tickets, {
+            weights: { ...configured?.weights, ...options.weights },
+            minScore: options.minScore ?? configured?.minScore,
+            limit: options.limit,
+        });
+    }
+    // Resolves an id/alias and optionally applies a status change. Does NOT
+    // persist — callers mutate further (notes, timestamps, resolution fields) and
+    // persist once when done, so those mutations are never lost.
+    async transitionTicket(rawId, status) {
+        const state = await this.ensureInitialized();
+        const targetId = normalizeTicketInput(rawId, state.tickets);
+        const ticket = state.tickets.find((entry) => entry.id === targetId);
+        if (!ticket) {
+            throw new Error(`Ticket not found: ${rawId}`);
+        }
+        if (status && ticket.status !== status) {
+            ticket.status = status;
+            ticket.updatedAt = nowIso();
+        }
+        return ticket;
+    }
+    attachPattern(state, family, ticketId) {
+        if (!this.config.patterns.autoCreateByFamily) {
+            return undefined;
+        }
+        const normalizedFamily = family || this.config.patterns.defaultFamily;
+        let pattern = state.patterns.find((entry) => entry.family === normalizedFamily && entry.status !== "resolved");
+        if (!pattern) {
+            pattern = {
+                id: patternId(++state.nextPatternSeq),
+                family: normalizedFamily,
+                title: `Recurring ${normalizedFamily} issues`,
+                status: "open",
+                createdAt: nowIso(),
+                updatedAt: nowIso(),
+                ticketIds: [],
+            };
+            state.patterns.push(pattern);
+        }
+        if (!pattern.ticketIds.includes(ticketId)) {
+            pattern.ticketIds.push(ticketId);
+            if (pattern.ticketIds.length >= 2) {
+                pattern.status = "active";
+            }
+        }
+        pattern.updatedAt = nowIso();
+        return pattern.id;
+    }
+    async persist() {
+        if (!this.state) {
+            return;
+        }
+        this.state.updatedAt = nowIso();
+        await this.backend.save(this.state);
+    }
+    get nowState() {
+        return nowIso();
+    }
+}
+exports.AgentLoopStore = AgentLoopStore;
+function normalizeTicketInput(raw, tickets) {
+    const normalized = raw.toUpperCase();
+    const match = /^([A-Z]+)-(\d{1,})$/.exec(normalized);
+    if (!match) {
+        return raw.toUpperCase();
+    }
+    const prefix = match[1];
+    const seq = match[2];
+    const canonical = `ISSUE-${seq}`;
+    if (prefix === "ISSUE") {
+        return canonical;
+    }
+    const found = tickets.find((ticket) => ticket.aliases.includes(`${prefix}-${seq}`));
+    if (found) {
+        return found.id;
+    }
+    return canonical;
+}
+//# sourceMappingURL=store.js.map

package/dist/types.d.ts

@@ -0,0 +1,156 @@
+export type TicketKind = "bug" | "feature" | "user_feedback" | "investigation" | "incident" | "tech_debt" | "task";
+export type TicketStatus = "triaged" | "active" | "resolved" | "reopened" | "deferred";
+export type PatternStatus = "open" | "active" | "resolved" | "reopened";
+export type Severity = "low" | "medium" | "high" | "critical";
+export type Confidence = "low" | "medium" | "high";
+export type GuardStatus = "guard_added" | "guard_existing" | "guard_waived" | "guard_deferred" | "none";
+export type NoteType = "hypothesis" | "related_history" | "prior_fix" | "triage" | "investigation";
+export interface KindConfig {
+    kind: TicketKind;
+    defaultSeverity: Severity;
+    requiredFields?: string[];
+}
+/**
+ * A queue routes tickets to a single user-facing alias prefix. Queues are
+ * evaluated in order (first match wins); a `source` match takes the precedence
+ * of the queue it belongs to, so e.g. a `user_report`-sourced bug routes to the
+ * USER queue rather than ISSUE.
+ */
+export interface QueueConfig {
+    /** Alias prefix, e.g. "USER", "DEV", "ISSUE". */
+    prefix: string;
+    /** Ticket kinds routed to this queue. */
+    kinds?: TicketKind[];
+    /** Sources routed to this queue, overriding kind routing. */
+    sources?: string[];
+    /** Fallback queue when nothing else matches. Exactly one queue should set this. */
+    default?: boolean;
+}
+export interface ProjectConfig {
+    projectName: string;
+    description: string;
+    defaultKind: TicketKind;
+    ticketKinds: KindConfig[];
+    queues: QueueConfig[];
+    sources: string[];
+    patterns: {
+        autoCreateByFamily: boolean;
+        defaultFamily: string;
+    };
+    /** Optional overrides for prior-art relatedness scoring. Core defaults apply when omitted. */
+    priorArt?: {
+        weights?: Partial<{
+            family: number;
+            pattern: number;
+            tag: number;
+            kind: number;
+            textOverlap: number;
+        }>;
+        minScore?: number;
+    };
+    /** Optional config-driven redaction. Library users can also inject a TicketRedactor directly. */
+    redaction?: {
+        patterns?: RedactionRule[];
+    };
+    /**
+     * Optional storage selection for the CLI/MCP. Prefer the `DATABASE_URL`
+     * environment variable for the connection string (it takes precedence) so
+     * secrets stay out of committed config.
+     */
+    storage?: {
+        databaseUrl?: string;
+    };
+}
+/** Context passed to a redactor so host implementations can vary behavior by field/ticket. */
+export interface RedactionContext {
+    field: string;
+    ticketKind?: string;
+    source?: string;
+}
+/**
+ * Host-pluggable redaction hook. Core ships a no-op default and a config-driven
+ * pattern redactor; host apps own real PII/secret scrubbing.
+ */
+export interface TicketRedactor {
+    redactText(value: string, context: RedactionContext): string;
+    redactJson(value: unknown, context: RedactionContext): unknown;
+}
+/** A single config-driven redaction rule (regex → replacement). */
+export interface RedactionRule {
+    name?: string;
+    /** Regular-expression source. */
+    pattern: string;
+    /** Regex flags; defaults to "g". */
+    flags?: string;
+    /** Replacement string; defaults to "[redacted]". */
+    replacement?: string;
+}
+export interface TicketNote {
+    id: string;
+    type: NoteType;
+    body: string;
+    author?: string;
+    createdAt: string;
+}
+export interface Ticket {
+    id: string;
+    family: string;
+    kind: TicketKind;
+    source: string;
+    title: string;
+    summary: string;
+    severity: Severity;
+    confidence: Confidence;
+    status: TicketStatus;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    resolvedAt?: string;
+    aliases: string[];
+    tags: string[];
+    notes: TicketNote[];
+    handoffText?: string;
+    guardStatus?: GuardStatus;
+    guardSummary?: string;
+    patternId?: string;
+    verification?: string;
+    reproducible?: boolean;
+    resolutionSummary?: string;
+}
+export interface Pattern {
+    id: string;
+    family: string;
+    title: string;
+    status: PatternStatus;
+    createdAt: string;
+    updatedAt: string;
+    ticketIds: string[];
+}
+export interface LoopState {
+    version: number;
+    project: string;
+    createdAt: string;
+    updatedAt: string;
+    nextTicketSeq: number;
+    nextPatternSeq: number;
+    tickets: Ticket[];
+    patterns: Pattern[];
+}
+export interface CreateTicketInput {
+    title: string;
+    summary: string;
+    family: string;
+    kind: TicketKind;
+    source: string;
+    severity?: Severity;
+    confidence?: Confidence;
+    tags?: string[];
+    handoffText?: string;
+}
+export interface ResolveInput {
+    id: string;
+    summary: string;
+    verification?: string;
+    guardStatus?: GuardStatus;
+    guardSummary?: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/docs/architecture.md

@@ -0,0 +1,30 @@
+# Architecture
+
+IntiDev AgentLoops is organized around a tiny local persistence and CLI layer:
+
+## Core primitives
+
+- `src/store.ts`
+  - owns durable state in `.agentloops/state.json`
+  - manages create/list/update transitions
+  - maintains ticket aliases and simple pattern grouping
+- `src/config.ts`
+  - project-level config schema and defaults
+  - alias mapping and required fields
+- `src/cli.ts`
+  - command parser and user-facing workflows
+- `agentloop.config.json`
+  - local configuration created from template
+
+## Extensibility points
+
+- ticket kinds and aliases can be customized in config
+- custom required fields are represented through `requiredFields` per kind
+- patterns currently group by family; teams can replace that in a fork or add source-level adapters
+
+## Planned extraction roadmap
+
+1. add MCP read-only tools for dashboard integrations,
+2. add pluggable storage adapters (SQLite/Postgres/HTTP API),
+3. add source adapters (Sentry, GitHub, Linear, Jira),
+4. split CLI/API/SDK packages.