tack-cli 0.1.0

package/dist/engine/cleanup.js

@@ -0,0 +1,101 @@
+import { grepFiles, listProjectFiles, readJson, fileExists } from "../lib/files.js";
+const SYSTEM_CLEANUP_MAP = {
+    auth: {
+        packages: [
+            "@clerk/nextjs",
+            "@clerk/clerk-react",
+            "next-auth",
+            "@auth/core",
+            "@auth0/nextjs-auth0",
+            "passport",
+            "lucia",
+            "@supabase/auth-helpers-nextjs",
+        ],
+        grepPatterns: [/ClerkProvider|NextAuth|Auth0Provider|passport\.authenticate|Lucia/],
+        configFiles: ["auth.ts", "auth.config.ts", "src/auth.ts", "middleware.ts"],
+    },
+    payments: {
+        packages: [
+            "stripe",
+            "@stripe/stripe-js",
+            "@stripe/react-stripe-js",
+            "@paddle/paddle-js",
+            "@lemonsqueezy/lemonsqueezy.js",
+        ],
+        grepPatterns: [/stripe|Stripe|paddle|lemonSqueezy/i],
+        configFiles: [],
+    },
+    db: {
+        packages: [
+            "prisma",
+            "@prisma/client",
+            "drizzle-orm",
+            "drizzle-kit",
+            "typeorm",
+            "mongoose",
+            "knex",
+            "pg",
+            "mysql2",
+        ],
+        grepPatterns: [/prisma|drizzle|typeorm|mongoose|knex/i],
+        configFiles: ["prisma/schema.prisma", "drizzle.config.ts", "ormconfig.json"],
+    },
+    multi_tenant: {
+        packages: [],
+        grepPatterns: [/Organization|orgId|teamId|workspaceId|tenantId/],
+        configFiles: ["prisma/schema.prisma"],
+    },
+    admin_panel: {
+        packages: [],
+        grepPatterns: [/isAdmin|requireAdmin|adminOnly|AdminGuard/],
+        configFiles: [],
+    },
+    background_jobs: {
+        packages: ["bullmq", "bull", "agenda", "node-cron", "cron", "inngest", "@trigger.dev/sdk"],
+        grepPatterns: [/Queue|Worker|Bull|agenda|cron\.schedule/i],
+        configFiles: [],
+    },
+    exports: {
+        packages: ["jspdf", "pdfkit", "@react-pdf/renderer", "puppeteer", "playwright", "exceljs", "xlsx"],
+        grepPatterns: [/jsPDF|PDFDocument|renderToStream/],
+        configFiles: [],
+    },
+};
+export function generateCleanupPlan(systemId) {
+    const mapping = SYSTEM_CLEANUP_MAP[systemId];
+    if (!mapping) {
+        return {
+            system: systemId,
+            packagesToRemove: [],
+            filesToReview: [],
+            configFilesToCheck: [],
+            summary: `No cleanup mapping found for system "${systemId}". Manual review required.`,
+        };
+    }
+    const pkg = readJson("package.json");
+    const allDeps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    const packagesToRemove = mapping.packages.filter((p) => p in allDeps);
+    const projectFiles = listProjectFiles();
+    const filesToReview = mapping.grepPatterns.flatMap((pattern) => grepFiles(projectFiles, pattern, 20));
+    const uniqueFiles = new Map();
+    for (const match of filesToReview) {
+        const key = `${match.file}:${match.line}`;
+        if (!uniqueFiles.has(key))
+            uniqueFiles.set(key, match);
+    }
+    const configFilesToCheck = mapping.configFiles.filter((f) => fileExists(f));
+    const summary = [
+        packagesToRemove.length > 0 ? `Remove ${packagesToRemove.length} package(s): ${packagesToRemove.join(", ")}` : null,
+        uniqueFiles.size > 0 ? `Review ${uniqueFiles.size} file reference(s)` : null,
+        configFilesToCheck.length > 0 ? `Check ${configFilesToCheck.length} config file(s)` : null,
+    ]
+        .filter(Boolean)
+        .join(". ");
+    return {
+        system: systemId,
+        packagesToRemove,
+        filesToReview: Array.from(uniqueFiles.values()),
+        configFilesToCheck,
+        summary: summary || "No cleanup actions identified.",
+    };
+}

package/dist/engine/compaction.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Archives handoff pairs (`.json` + `.md`) older than the most recent `keepRecent`.
+ * Moves them into `.tack/handoffs/archive/` so pairs are never split.
+ */
+export declare function archiveOldHandoffs(keepRecent?: number): void;

package/dist/engine/compaction.js

@@ -0,0 +1,44 @@
+import { existsSync, mkdirSync, readdirSync, renameSync } from "node:fs";
+import * as path from "node:path";
+import { handoffsDirPath } from "../lib/files.js";
+import { log } from "../lib/logger.js";
+/**
+ * Archives handoff pairs (`.json` + `.md`) older than the most recent `keepRecent`.
+ * Moves them into `.tack/handoffs/archive/` so pairs are never split.
+ */
+export function archiveOldHandoffs(keepRecent = 10) {
+    const handoffsDir = handoffsDirPath();
+    if (!existsSync(handoffsDir))
+        return;
+    const entries = readdirSync(handoffsDir, { withFileTypes: true });
+    const files = entries
+        .filter((e) => e.isFile() && (e.name.endsWith(".json") || e.name.endsWith(".md")))
+        .map((e) => e.name);
+    // Group by stem (basename without extension) so we keep/archive whole pairs
+    const byStem = new Map();
+    for (const f of files) {
+        const stem = path.basename(f, path.extname(f));
+        const list = byStem.get(stem) ?? [];
+        list.push(f);
+        byStem.set(stem, list);
+    }
+    const stems = Array.from(byStem.keys()).sort().reverse();
+    const toKeep = stems.slice(0, keepRecent);
+    const toArchive = stems.slice(keepRecent);
+    if (toArchive.length === 0)
+        return;
+    const archiveDir = path.join(handoffsDir, "archive");
+    mkdirSync(archiveDir, { recursive: true });
+    let archivedCount = 0;
+    for (const stem of toArchive) {
+        for (const file of byStem.get(stem) ?? []) {
+            renameSync(path.join(handoffsDir, file), path.join(archiveDir, file));
+            archivedCount++;
+        }
+    }
+    log({
+        event: "compaction:archive_handoffs",
+        archived_count: archivedCount,
+        kept_count: toKeep.length,
+    });
+}

package/dist/engine/compareSpec.d.ts

@@ -0,0 +1,2 @@
+import type { Signal, Spec, SpecDiff } from "../lib/signals.js";
+export declare function compareSpec(signals: Signal[], spec: Spec): SpecDiff;

package/dist/engine/compareSpec.js

@@ -0,0 +1,74 @@
+export function compareSpec(signals, spec) {
+    const systems = signals.filter((s) => s.category === "system");
+    const scopes = signals.filter((s) => s.category === "scope");
+    const risks = signals.filter((s) => s.category === "risk");
+    const aligned = [];
+    const violations = [];
+    const undeclared = [];
+    for (const sig of systems) {
+        if (spec.allowed_systems.includes(sig.id)) {
+            aligned.push(sig);
+        }
+        else if (spec.forbidden_systems.includes(sig.id)) {
+            violations.push({
+                type: "forbidden_system",
+                signal: sig,
+                spec_rule: `forbidden_systems contains "${sig.id}"`,
+                severity: "error",
+            });
+        }
+        else {
+            undeclared.push(sig);
+        }
+    }
+    for (const sig of scopes) {
+        if (spec.forbidden_systems.includes(sig.id)) {
+            violations.push({
+                type: "forbidden_system",
+                signal: sig,
+                spec_rule: `forbidden_systems contains "${sig.id}"`,
+                severity: "error",
+            });
+        }
+        else if (!spec.allowed_systems.includes(sig.id)) {
+            undeclared.push(sig);
+        }
+        else {
+            aligned.push(sig);
+        }
+    }
+    for (const [key, expectedValue] of Object.entries(spec.constraints)) {
+        const matchingSignal = systems.find((s) => {
+            if (key === "framework")
+                return s.id === "framework";
+            if (key === "db")
+                return s.id === "db";
+            if (key === "auth")
+                return s.id === "auth";
+            if (key === "deploy")
+                return s.id === "deploy";
+            return false;
+        });
+        if (matchingSignal?.detail) {
+            const detectedDetail = matchingSignal.detail.toLowerCase();
+            const expected = expectedValue.toLowerCase();
+            if (!detectedDetail.includes(expected)) {
+                violations.push({
+                    type: "constraint_mismatch",
+                    signal: matchingSignal,
+                    spec_rule: `constraints.${key} expects "${expectedValue}" but found "${matchingSignal.detail}"`,
+                    severity: "error",
+                });
+            }
+        }
+    }
+    const detectedIds = new Set([...systems.map((s) => s.id), ...scopes.map((s) => s.id)]);
+    const missing = spec.allowed_systems.filter((id) => !detectedIds.has(id));
+    return {
+        aligned,
+        violations,
+        undeclared,
+        missing,
+        risks,
+    };
+}

package/dist/engine/computeDrift.d.ts

@@ -0,0 +1,6 @@
+import type { SpecDiff, DriftState, DriftItem } from "../lib/signals.js";
+export declare function computeDrift(diff: SpecDiff): {
+    newItems: DriftItem[];
+    state: DriftState;
+};
+export declare function resolveDriftItem(id: string, action: "accepted" | "rejected" | "skipped", note?: string): DriftState;

package/dist/engine/computeDrift.js

@@ -0,0 +1,133 @@
+import { createDriftId } from "../lib/signals.js";
+import { readDrift, writeDrift } from "../lib/files.js";
+import { log } from "../lib/logger.js";
+export function computeDrift(diff) {
+    const existing = readDrift();
+    const newItems = [];
+    const existingFingerprints = new Set(existing.items.map((item) => fingerprint(item)));
+    // Build the set of drift fingerprints that are still present in the latest spec diff.
+    const currentFingerprints = new Set();
+    for (const violation of diff.violations) {
+        const type = violation.type === "forbidden_system" ? "forbidden_system_detected" : "constraint_mismatch";
+        const fpItem = {
+            id: "",
+            type,
+            system: violation.signal.id,
+            signal: "",
+            detected: "",
+            status: "unresolved",
+        };
+        currentFingerprints.add(fingerprint(fpItem));
+    }
+    for (const risk of diff.risks) {
+        const fpItem = {
+            id: "",
+            type: "risk",
+            risk: risk.id,
+            signal: "",
+            detected: "",
+            status: "unresolved",
+        };
+        currentFingerprints.add(fingerprint(fpItem));
+    }
+    for (const sig of diff.undeclared) {
+        const fpItem = {
+            id: "",
+            type: "undeclared_system",
+            system: sig.id,
+            signal: "",
+            detected: "",
+            status: "unresolved",
+        };
+        currentFingerprints.add(fingerprint(fpItem));
+    }
+    // Automatically resolve drift items whose underlying fingerprint is no longer present.
+    for (const item of existing.items) {
+        const fp = fingerprint(item);
+        if (item.status === "unresolved" && !currentFingerprints.has(fp)) {
+            item.status = "rejected";
+            log({
+                event: "drift:resolved",
+                system: item.system ?? item.risk ?? item.type,
+                message: item.signal,
+                source: ".tack/_drift.yaml",
+            });
+        }
+    }
+    for (const violation of diff.violations) {
+        const item = {
+            id: createDriftId(),
+            type: violation.type === "forbidden_system" ? "forbidden_system_detected" : "constraint_mismatch",
+            system: violation.signal.id,
+            signal: `${violation.signal.detail ?? violation.signal.id}: ${violation.signal.source}`,
+            detected: new Date().toISOString(),
+            status: "unresolved",
+        };
+        if (!existingFingerprints.has(fingerprint(item))) {
+            newItems.push(item);
+        }
+    }
+    for (const risk of diff.risks) {
+        const item = {
+            id: createDriftId(),
+            type: "risk",
+            risk: risk.id,
+            signal: `${risk.detail ?? risk.id}: ${risk.source}`,
+            detected: new Date().toISOString(),
+            status: "unresolved",
+        };
+        if (!existingFingerprints.has(fingerprint(item))) {
+            newItems.push(item);
+        }
+    }
+    for (const sig of diff.undeclared) {
+        const item = {
+            id: createDriftId(),
+            type: "undeclared_system",
+            system: sig.id,
+            signal: `${sig.detail ?? sig.id}: ${sig.source}`,
+            detected: new Date().toISOString(),
+            status: "unresolved",
+        };
+        if (!existingFingerprints.has(fingerprint(item))) {
+            newItems.push(item);
+        }
+    }
+    const state = {
+        items: [...existing.items, ...newItems],
+    };
+    writeDrift(state);
+    for (const item of newItems) {
+        log({
+            event: "drift:detected",
+            system: item.system ?? item.risk ?? item.type,
+            message: item.signal,
+            source: ".tack/_drift.yaml",
+        });
+    }
+    return { newItems, state };
+}
+export function resolveDriftItem(id, action, note) {
+    const state = readDrift();
+    const item = state.items.find((i) => i.id === id);
+    let previousStatus = null;
+    if (item) {
+        previousStatus = item.status;
+        item.status = action === "skipped" ? "unresolved" : action;
+        if (note)
+            item.note = note;
+    }
+    writeDrift(state);
+    if (item && previousStatus === "unresolved" && item.status !== "unresolved") {
+        log({
+            event: "drift:resolved",
+            system: item.system ?? item.risk ?? item.type,
+            message: item.signal,
+            source: ".tack/_drift.yaml",
+        });
+    }
+    return state;
+}
+function fingerprint(item) {
+    return `${item.type}:${item.system ?? ""}:${item.risk ?? ""}`;
+}

package/dist/engine/contextPack.d.ts

@@ -0,0 +1,4 @@
+import type { ContextLineRef, ContextPack, DecisionEntry } from "../lib/signals.js";
+export declare function parseDecisionsMarkdown(content: string, file?: string): DecisionEntry[];
+export declare function parseContextPack(): ContextPack;
+export declare function contextRefToString(ref: ContextLineRef): string;

package/dist/engine/contextPack.js

@@ -0,0 +1,169 @@
+import { assumptionsPath, contextPath, implementationStatusPath, decisionsPath, goalsPath, openQuestionsPath, readFile, } from "../lib/files.js";
+function parseBulletsInSection(content, sectionName, file) {
+    const lines = content.split("\n");
+    const out = [];
+    let inSection = false;
+    const target = `## ${sectionName}`.toLowerCase();
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i] ?? "";
+        const line = raw.trim();
+        if (line.toLowerCase() === target) {
+            inSection = true;
+            continue;
+        }
+        if (inSection && line.startsWith("## ")) {
+            break;
+        }
+        if (inSection && line.startsWith("- ")) {
+            const text = line.slice(2).trim();
+            if (text.length > 0) {
+                out.push({ text, source: { file, line: i + 1 } });
+            }
+        }
+    }
+    return out;
+}
+function parseQuestionStatus(line) {
+    const match = line.match(/^\[(open|resolved)\]\s*(.*)$/i);
+    if (!match) {
+        return { status: "unknown", text: line.trim() };
+    }
+    const rawStatus = (match[1] ?? "").toLowerCase();
+    const status = rawStatus === "open" || rawStatus === "resolved" ? rawStatus : "unknown";
+    return {
+        status,
+        text: (match[2] ?? "").trim(),
+    };
+}
+function parseQuestionBullets(content, file) {
+    const lines = content.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = (lines[i] ?? "").trim();
+        if (!line.startsWith("- "))
+            continue;
+        const payload = line.slice(2).trim();
+        if (!payload)
+            continue;
+        const parsed = parseQuestionStatus(payload);
+        if (parsed.text.length === 0)
+            continue;
+        out.push({
+            status: parsed.status,
+            text: parsed.text,
+            source: { file, line: i + 1 },
+        });
+    }
+    return out;
+}
+export function parseDecisionsMarkdown(content, file = ".tack/decisions.md") {
+    if (!content)
+        return [];
+    const lines = content.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = (lines[i] ?? "").trim();
+        if (!line.startsWith("- "))
+            continue;
+        const m = line.match(/^-\s*\[(\d{4}-\d{2}-\d{2})\]\s*(.+?)\s*—\s*(.+)$/);
+        if (!m)
+            continue;
+        out.push({
+            date: m[1] ?? "",
+            decision: (m[2] ?? "").trim(),
+            reasoning: (m[3] ?? "").trim(),
+            source: { file, line: i + 1 },
+        });
+    }
+    return out;
+}
+function parseDecisionsFile() {
+    const content = readFile(decisionsPath());
+    if (!content)
+        return [];
+    return parseDecisionsMarkdown(content, ".tack/decisions.md");
+}
+function parseContextFile() {
+    const file = ".tack/context.md";
+    const content = readFile(contextPath());
+    if (!content)
+        return [];
+    return parseBulletsInSection(content, "North Star", file);
+}
+function parseGoalsFile() {
+    const file = ".tack/goals.md";
+    const content = readFile(goalsPath());
+    if (!content)
+        return { goals: [], nonGoals: [] };
+    return {
+        goals: parseBulletsInSection(content, "Goals", file),
+        nonGoals: parseBulletsInSection(content, "Non-Goals", file),
+    };
+}
+function parseAssumptionsFile() {
+    const file = ".tack/assumptions.md";
+    const content = readFile(assumptionsPath());
+    if (!content)
+        return [];
+    return parseQuestionBullets(content, file);
+}
+function parseOpenQuestionsFile() {
+    const file = ".tack/open_questions.md";
+    const content = readFile(openQuestionsPath());
+    if (!content)
+        return [];
+    return parseQuestionBullets(content, file);
+}
+function parseImplementationStatusFile() {
+    const file = ".tack/implementation_status.md";
+    const content = readFile(implementationStatusPath());
+    if (!content)
+        return [];
+    const lines = content.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = (lines[i] ?? "").trim();
+        if (!line.startsWith("- "))
+            continue;
+        const payload = line.slice(2).trim();
+        if (!payload)
+            continue;
+        const m = payload.match(/^([a-z0-9_.-]+)\s*:\s*(implemented|pending|unknown)\s*(?:\((.+)\))?$/i);
+        if (!m)
+            continue;
+        const key = (m[1] ?? "").trim();
+        const status = (m[2] ?? "").toLowerCase() || "unknown";
+        const anchorsRaw = (m[3] ?? "").trim();
+        const anchors = anchorsRaw.length === 0
+            ? []
+            : anchorsRaw
+                .split(",")
+                .map((a) => a.trim())
+                .filter(Boolean);
+        if (!key)
+            continue;
+        out.push({
+            key,
+            status,
+            anchors,
+            source: { file, line: i + 1 },
+        });
+    }
+    return out;
+}
+export function parseContextPack() {
+    const northStar = parseContextFile();
+    const goals = parseGoalsFile();
+    return {
+        north_star: northStar,
+        goals: goals.goals,
+        non_goals: goals.nonGoals,
+        assumptions: parseAssumptionsFile(),
+        open_questions: parseOpenQuestionsFile(),
+        implementation_status: parseImplementationStatusFile(),
+        decisions: parseDecisionsFile(),
+    };
+}
+export function contextRefToString(ref) {
+    return `${ref.file}:${ref.line}`;
+}

package/dist/engine/decisions.d.ts

@@ -0,0 +1,4 @@
+import type { DecisionActor } from "../lib/signals.js";
+export declare function appendDecision(decision: string, reasoning: string): void;
+export declare function readDecisionsMarkdown(): string;
+export declare function normalizeDecisionActor(raw: string | undefined): DecisionActor;

package/dist/engine/decisions.js

@@ -0,0 +1,21 @@
+import { appendSafe, decisionsPath, readFile, ensureContextTemplates } from "../lib/files.js";
+function todayIsoDate() {
+    return new Date().toISOString().slice(0, 10);
+}
+export function appendDecision(decision, reasoning) {
+    ensureContextTemplates();
+    const line = `- [${todayIsoDate()}] ${decision} — ${reasoning}\n`;
+    appendSafe(decisionsPath(), line);
+}
+export function readDecisionsMarkdown() {
+    ensureContextTemplates();
+    return readFile(decisionsPath()) ?? "# Decisions\n";
+}
+export function normalizeDecisionActor(raw) {
+    if (!raw || raw.trim() === "")
+        return "user";
+    const value = raw.trim();
+    if (value === "user" || value.startsWith("agent:"))
+        return value;
+    return "user";
+}

package/dist/engine/diff.d.ts

@@ -0,0 +1,46 @@
+import { type DriftItem, type DriftState, type DecisionEntry, type Spec } from "../lib/signals.js";
+export type ArchSystem = {
+    id: string;
+    detail?: string;
+};
+export type ArchSnapshot = {
+    ref: string;
+    spec: Spec | null;
+    systems: ArchSystem[];
+    drift: DriftState | null;
+    decisions: DecisionEntry[];
+    hasSpec: boolean;
+    hasAudit: boolean;
+    hasDrift: boolean;
+};
+export type DriftResolutionChange = {
+    id: string;
+    before: DriftItem | null;
+    after: DriftItem | null;
+};
+export type ArchDiff = {
+    baseRef: string;
+    headRef: string;
+    systems: {
+        available: boolean;
+        added: ArchSystem[];
+        removed: ArchSystem[];
+        changed: Array<{
+            id: string;
+            before: ArchSystem;
+            after: ArchSystem;
+        }>;
+    };
+    drift: {
+        available: boolean;
+        newlyUnresolved: DriftItem[];
+        resolved: DriftResolutionChange[];
+    };
+    decisions: {
+        newDecisions: DecisionEntry[];
+    };
+    warnings: string[];
+};
+export declare function computeArchSnapshotFromWorkingTree(): ArchSnapshot;
+export declare function computeArchSnapshotFromRef(ref: string): ArchSnapshot;
+export declare function computeArchDiff(baseBranch: string): ArchDiff;