tack-cli 0.1.0

package/dist/lib/validate.js

@@ -0,0 +1,282 @@
+import * as path from "node:path";
+import { KNOWN_CONSTRAINT_KEYS } from "./signals.js";
+const MAX_FIELD_LENGTH = 200;
+const MAX_SOURCE_LENGTH = 500;
+const SPEC_KEYS = new Set(["project", "allowed_systems", "forbidden_systems", "constraints", "domains"]);
+const DRIFT_TYPES = new Set([
+    "forbidden_system_detected",
+    "constraint_mismatch",
+    "risk",
+    "undeclared_system",
+]);
+const DRIFT_STATUS = new Set(["unresolved", "accepted", "rejected"]);
+const KNOWN_CONSTRAINTS = new Set(KNOWN_CONSTRAINT_KEYS);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cleanString(input, field, warnings, max = MAX_FIELD_LENGTH) {
+    const stripped = input.replace(/[\n\r\t\x00-\x1f]/g, "").trim();
+    if (stripped !== input) {
+        warnings.push(`Suspicious characters stripped from ${field}`);
+    }
+    if (stripped.length > max) {
+        warnings.push(`Field ${field} exceeded ${max} chars and was truncated`);
+        return stripped.slice(0, max);
+    }
+    return stripped;
+}
+function sanitizeStringArray(value, field, warnings, max = MAX_FIELD_LENGTH) {
+    if (!Array.isArray(value)) {
+        if (value !== undefined)
+            warnings.push(`Expected array for ${field}, got ${typeof value}`);
+        return [];
+    }
+    return value
+        .flatMap((item) => {
+        if (typeof item !== "string") {
+            warnings.push(`Non-string value in ${field} skipped`);
+            return [];
+        }
+        const cleaned = cleanString(item, field, warnings, max);
+        return cleaned ? [cleaned] : [];
+    })
+        .filter((v, i, arr) => arr.indexOf(v) === i);
+}
+export function validateSpec(raw, projectRoot) {
+    const warnings = [];
+    if (!isRecord(raw)) {
+        if (raw !== null && raw !== undefined) {
+            warnings.push("spec.yaml root must be a mapping/object");
+        }
+        return { data: null, warnings };
+    }
+    for (const key of Object.keys(raw)) {
+        if (!SPEC_KEYS.has(key))
+            warnings.push(`Unknown key "${key}" in spec.yaml ignored`);
+    }
+    const fallbackProject = path.basename(projectRoot);
+    const project = typeof raw.project === "string"
+        ? cleanString(raw.project, "project", warnings)
+        : fallbackProject;
+    const allowed = sanitizeStringArray(raw.allowed_systems, "allowed_systems", warnings);
+    const forbidden = sanitizeStringArray(raw.forbidden_systems, "forbidden_systems", warnings);
+    const constraints = {};
+    if (raw.constraints !== undefined && !isRecord(raw.constraints)) {
+        warnings.push("constraints must be an object map and was reset");
+    }
+    else if (isRecord(raw.constraints)) {
+        for (const [key, value] of Object.entries(raw.constraints)) {
+            if (!KNOWN_CONSTRAINTS.has(key)) {
+                warnings.push(`Unknown constraint key "${key}" ignored`);
+                continue;
+            }
+            if (typeof value !== "string") {
+                warnings.push(`Constraint "${key}" must be a string and was ignored`);
+                continue;
+            }
+            const cleaned = cleanString(value, `constraints.${key}`, warnings);
+            if (!cleaned) {
+                warnings.push(`Constraint "${key}" was empty after sanitization and removed`);
+                continue;
+            }
+            constraints[key] = cleaned;
+        }
+    }
+    let domains;
+    if (raw.domains !== undefined) {
+        if (!isRecord(raw.domains)) {
+            warnings.push("domains must be an object map and was ignored");
+        }
+        else {
+            const domainEntries = {};
+            for (const [rawId, rawDomain] of Object.entries(raw.domains)) {
+                const id = cleanString(String(rawId), "domains.key", warnings);
+                if (!id) {
+                    warnings.push("Empty domain key after sanitization was skipped");
+                    continue;
+                }
+                if (!isRecord(rawDomain)) {
+                    warnings.push(`Domain "${id}" must be an object and was skipped`);
+                    continue;
+                }
+                const domain = {};
+                if (typeof rawDomain.label === "string") {
+                    const label = cleanString(rawDomain.label, `domains.${id}.label`, warnings);
+                    if (label)
+                        domain.label = label;
+                }
+                if (rawDomain.systems !== undefined) {
+                    const systems = sanitizeStringArray(rawDomain.systems, `domains.${id}.systems`, warnings);
+                    if (systems.length > 0)
+                        domain.systems = systems;
+                }
+                if (rawDomain.constraints !== undefined) {
+                    const rawList = sanitizeStringArray(rawDomain.constraints, `domains.${id}.constraints`, warnings);
+                    const filtered = rawList.filter((c) => {
+                        if (!KNOWN_CONSTRAINTS.has(c)) {
+                            warnings.push(`Unknown constraint key "${c}" in domains.${id}.constraints ignored`);
+                            return false;
+                        }
+                        return true;
+                    });
+                    if (filtered.length > 0)
+                        domain.constraints = filtered;
+                }
+                if (Object.keys(domain).length === 0) {
+                    warnings.push(`Domain "${id}" was empty after sanitization and removed`);
+                    continue;
+                }
+                domainEntries[id] = domain;
+            }
+            if (Object.keys(domainEntries).length > 0) {
+                domains = domainEntries;
+            }
+        }
+    }
+    return {
+        data: {
+            project: project || fallbackProject,
+            allowed_systems: allowed,
+            forbidden_systems: forbidden,
+            constraints,
+            ...(domains ? { domains } : {}),
+        },
+        warnings,
+    };
+}
+function validateSignal(raw, bucket, warnings) {
+    if (!isRecord(raw)) {
+        warnings.push(`Invalid signal entry in ${bucket} list skipped`);
+        return null;
+    }
+    if (typeof raw.id !== "string" || typeof raw.source !== "string") {
+        warnings.push(`Signal in ${bucket} list missing id/source and was skipped`);
+        return null;
+    }
+    if (typeof raw.confidence !== "number" || Number.isNaN(raw.confidence)) {
+        warnings.push(`Signal ${raw.id} has invalid confidence and was skipped`);
+        return null;
+    }
+    if (raw.confidence < 0 || raw.confidence > 1) {
+        warnings.push(`Signal ${raw.id} confidence was clamped to 0-1`);
+    }
+    const signal = {
+        category: bucket,
+        id: cleanString(raw.id, `signal.${bucket}.id`, warnings),
+        source: cleanString(raw.source, `signal.${bucket}.source`, warnings, MAX_SOURCE_LENGTH),
+        confidence: Math.max(0, Math.min(1, raw.confidence)),
+    };
+    if (typeof raw.detail === "string") {
+        const detail = cleanString(raw.detail, `signal.${bucket}.detail`, warnings, MAX_SOURCE_LENGTH);
+        if (detail)
+            signal.detail = detail;
+    }
+    if (!signal.id || !signal.source) {
+        warnings.push(`Signal in ${bucket} list became empty after sanitization and was skipped`);
+        return null;
+    }
+    return signal;
+}
+export function validateAudit(raw) {
+    const warnings = [];
+    if (!isRecord(raw)) {
+        if (raw !== null && raw !== undefined)
+            warnings.push("_audit.yaml root must be an object");
+        return { data: null, warnings };
+    }
+    if (!isRecord(raw.signals)) {
+        warnings.push("_audit.yaml missing signals object");
+        return { data: null, warnings };
+    }
+    const systems = Array.isArray(raw.signals.systems)
+        ? raw.signals.systems.map((s) => validateSignal(s, "system", warnings)).filter((s) => s !== null)
+        : [];
+    const scopeSignals = Array.isArray(raw.signals.scope_signals)
+        ? raw.signals.scope_signals
+            .map((s) => validateSignal(s, "scope", warnings))
+            .filter((s) => s !== null)
+        : [];
+    const risks = Array.isArray(raw.signals.risks)
+        ? raw.signals.risks.map((s) => validateSignal(s, "risk", warnings)).filter((s) => s !== null)
+        : [];
+    if (!Array.isArray(raw.signals.systems))
+        warnings.push("_audit.yaml signals.systems was reset");
+    if (!Array.isArray(raw.signals.scope_signals))
+        warnings.push("_audit.yaml signals.scope_signals was reset");
+    if (!Array.isArray(raw.signals.risks))
+        warnings.push("_audit.yaml signals.risks was reset");
+    const timestamp = typeof raw.timestamp === "string" && raw.timestamp.trim()
+        ? cleanString(raw.timestamp, "audit.timestamp", warnings, MAX_SOURCE_LENGTH)
+        : new Date().toISOString();
+    return {
+        data: {
+            timestamp,
+            signals: {
+                systems,
+                scope_signals: scopeSignals,
+                risks,
+            },
+        },
+        warnings,
+    };
+}
+function validateDriftItem(raw, warnings) {
+    if (!isRecord(raw)) {
+        warnings.push("Invalid drift item skipped");
+        return null;
+    }
+    if (typeof raw.id !== "string" || typeof raw.signal !== "string") {
+        warnings.push("Drift item missing id/signal skipped");
+        return null;
+    }
+    if (typeof raw.type !== "string" || !DRIFT_TYPES.has(raw.type)) {
+        warnings.push(`Drift item ${raw.id} has unknown type and was skipped`);
+        return null;
+    }
+    const status = typeof raw.status === "string" && DRIFT_STATUS.has(raw.status)
+        ? raw.status
+        : "unresolved";
+    if (status !== raw.status)
+        warnings.push(`Drift item ${raw.id} had invalid status and defaulted to unresolved`);
+    const detected = typeof raw.detected === "string" && raw.detected.trim()
+        ? cleanString(raw.detected, `drift.${raw.id}.detected`, warnings, MAX_SOURCE_LENGTH)
+        : new Date().toISOString();
+    const item = {
+        id: cleanString(raw.id, "drift.id", warnings),
+        type: raw.type,
+        signal: cleanString(raw.signal, "drift.signal", warnings, MAX_SOURCE_LENGTH),
+        detected,
+        status,
+    };
+    if (typeof raw.system === "string")
+        item.system = cleanString(raw.system, "drift.system", warnings);
+    if (typeof raw.risk === "string")
+        item.risk = cleanString(raw.risk, "drift.risk", warnings);
+    if (typeof raw.constraint === "string") {
+        item.constraint = cleanString(raw.constraint, "drift.constraint", warnings);
+    }
+    if (typeof raw.note === "string")
+        item.note = cleanString(raw.note, "drift.note", warnings, MAX_SOURCE_LENGTH);
+    if (!item.id || !item.signal) {
+        warnings.push("Drift item became empty after sanitization and was skipped");
+        return null;
+    }
+    return item;
+}
+export function validateDriftState(raw) {
+    const warnings = [];
+    if (!isRecord(raw)) {
+        if (raw !== null && raw !== undefined)
+            warnings.push("_drift.yaml root must be an object");
+        return { data: { items: [] }, warnings };
+    }
+    if (!Array.isArray(raw.items)) {
+        if (raw.items !== undefined)
+            warnings.push("_drift.yaml items must be an array");
+        return { data: { items: [] }, warnings };
+    }
+    const items = raw.items
+        .map((item) => validateDriftItem(item, warnings))
+        .filter((item) => item !== null);
+    return { data: { items }, warnings };
+}

package/dist/lib/yaml.d.ts

@@ -0,0 +1,4 @@
+export declare function safeLoadYaml<T>(filepath: string, fallback: T): {
+    data: T;
+    error: string | null;
+};

package/dist/lib/yaml.js

@@ -0,0 +1,26 @@
+import { basename } from "node:path";
+import * as fs from "node:fs";
+import * as yaml from "js-yaml";
+export function safeLoadYaml(filepath, fallback) {
+    if (!fs.existsSync(filepath)) {
+        return { data: fallback, error: null };
+    }
+    let lastError = null;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            const raw = fs.readFileSync(filepath, "utf-8");
+            const parsed = yaml.load(raw);
+            if (parsed === null || parsed === undefined) {
+                return { data: fallback, error: null };
+            }
+            return { data: parsed, error: null };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const lineMatch = message.match(/line (\d+)/i);
+            const lineInfo = lineMatch ? ` (line ${lineMatch[1]})` : "";
+            lastError = `Failed to parse ${basename(filepath)}${lineInfo}: ${message}`;
+        }
+    }
+    return { data: fallback, error: lastError };
+}

package/dist/mcp.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp.js

@@ -0,0 +1,259 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import * as path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { contextPath, goalsPath, openQuestionsPath, decisionsPath, implementationStatusPath, specPath, auditPath, driftPath, handoffsDirPath, } from "./lib/files.js";
+import { parseContextPack } from "./engine/contextPack.js";
+import { wrapUntrustedContext } from "./lib/promptSafety.js";
+import { appendDecision, normalizeDecisionActor } from "./engine/decisions.js";
+import { log } from "./lib/logger.js";
+import { addNote } from "./lib/notes.js";
+import { AGENT_NOTE_TYPES } from "./lib/signals.js";
+function safeReadFile(filepath) {
+    try {
+        return readFileSync(filepath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+function latestHandoffJsonPath() {
+    const dir = handoffsDirPath();
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    const jsonFiles = entries.filter((f) => f.endsWith(".json"));
+    if (jsonFiles.length === 0)
+        return null;
+    jsonFiles.sort((a, b) => {
+        const aPath = path.join(dir, a);
+        const bPath = path.join(dir, b);
+        const aTime = statSync(aPath).mtimeMs;
+        const bTime = statSync(bPath).mtimeMs;
+        return bTime - aTime;
+    });
+    return path.join(dir, jsonFiles[0]);
+}
+async function main() {
+    const server = new McpServer({
+        name: "tack-mcp",
+        version: "0.1.0",
+    }, {});
+    // Intent: high-level purpose and goals, without architecture internals.
+    server.registerResource("intent", "tack://context/intent", {
+        title: "Tack Context – Intent",
+        description: "High-level North Star, goals, and open questions for this project.",
+        mimeType: "text/markdown",
+    }, async (uri) => {
+        const parts = [];
+        const context = safeReadFile(contextPath());
+        if (context) {
+            parts.push("# context.md", "", context.trim(), "");
+        }
+        const goals = safeReadFile(goalsPath());
+        if (goals) {
+            parts.push("# goals.md", "", goals.trim(), "");
+        }
+        const open = safeReadFile(openQuestionsPath());
+        if (open) {
+            parts.push("# open_questions.md", "", open.trim(), "");
+        }
+        const decisions = safeReadFile(decisionsPath());
+        if (decisions) {
+            parts.push("# decisions.md", "", decisions.trim(), "");
+        }
+        const text = parts.length > 0
+            ? parts.join("\n").trimEnd()
+            : "No context docs found in .tack/.";
+        const wrapped = wrapUntrustedContext(text, "tack://context/intent");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: wrapped,
+                },
+            ],
+        };
+    });
+    // Facts: implementation status and architecture spec (guardrails).
+    server.registerResource("facts", "tack://context/facts", {
+        title: "Tack Context – Facts",
+        description: "Binary, source-anchored implementation status and architecture spec.",
+        mimeType: "text/markdown",
+    }, async (uri) => {
+        const parts = [];
+        const impl = safeReadFile(implementationStatusPath());
+        if (impl) {
+            parts.push("# implementation_status.md", "", impl.trim(), "");
+        }
+        const spec = safeReadFile(specPath());
+        if (spec) {
+            parts.push("# spec.yaml", "", "```yaml", spec.trim(), "```", "");
+        }
+        const text = parts.length > 0
+            ? parts.join("\n").trimEnd()
+            : "No implementation_status.md or spec.yaml found in .tack/.";
+        const wrapped = wrapUntrustedContext(text, "tack://context/facts");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: wrapped,
+                },
+            ],
+        };
+    });
+    // Latest handoff JSON: canonical machine-readable summary for agents.
+    server.registerResource("handoff-latest", "tack://handoff/latest", {
+        title: "Tack Handoff – Latest",
+        description: "Latest handoff JSON generated by `tack handoff`.",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const jsonPath = latestHandoffJsonPath();
+        if (!jsonPath) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        text: JSON.stringify({ error: "No handoff JSON files found in .tack/handoffs/." }, null, 2),
+                    },
+                ],
+            };
+        }
+        const text = safeReadFile(jsonPath) ?? "";
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text,
+                },
+            ],
+        };
+    });
+    // Recent decisions: last N entries from the parsed context pack.
+    server.registerResource("decisions-recent", "tack://context/decisions_recent", {
+        title: "Tack Decisions – Recent",
+        description: "Recent architecture and product decisions driving this project.",
+        mimeType: "text/markdown",
+    }, async (uri) => {
+        const pack = parseContextPack();
+        const recent = pack.decisions.slice(-10);
+        if (recent.length === 0) {
+            const wrappedEmpty = wrapUntrustedContext("No decisions recorded yet in .tack/decisions.md.", "tack://context/decisions_recent");
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        text: wrappedEmpty,
+                    },
+                ],
+            };
+        }
+        const lines = ["# Recent Decisions", ""];
+        for (const d of recent) {
+            lines.push(`- [${d.date}] ${d.decision} — ${d.reasoning}`);
+        }
+        const wrapped = wrapUntrustedContext(lines.join("\n"), "tack://context/decisions_recent");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: wrapped,
+                },
+            ],
+        };
+    });
+    // Machine state overview: audit and drift files, for engineering tasks.
+    server.registerResource("machine-state", "tack://context/machine_state", {
+        title: "Tack Machine State",
+        description: "Raw machine state from _audit.yaml and _drift.yaml.",
+        mimeType: "text/markdown",
+    }, async (uri) => {
+        const parts = [];
+        const audit = safeReadFile(auditPath());
+        if (audit) {
+            parts.push("# _audit.yaml", "", "```yaml", audit.trim(), "```", "");
+        }
+        const drift = safeReadFile(driftPath());
+        if (drift) {
+            parts.push("# _drift.yaml", "", "```yaml", drift.trim(), "```", "");
+        }
+        const text = parts.length > 0
+            ? parts.join("\n").trimEnd()
+            : "No _audit.yaml or _drift.yaml found in .tack/.";
+        const wrapped = wrapUntrustedContext(text, "tack://context/machine_state");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: wrapped,
+                },
+            ],
+        };
+    });
+    // Tools: write-back channels for agents.
+    server.registerTool("log_decision", {
+        description: "Record a decision with reasoning into .tack/decisions.md and the Tack event log.",
+        inputSchema: z.object({
+            decision: z.string().min(1),
+            reasoning: z.string().min(1),
+            actor: z.string().optional(),
+        }),
+    }, async (args) => {
+        const decision = args.decision;
+        const reasoning = args.reasoning;
+        const actor = typeof args.actor === "string" ? args.actor : undefined;
+        appendDecision(decision, reasoning);
+        log({
+            event: "decision",
+            decision,
+            reasoning,
+            actor: normalizeDecisionActor(actor),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Decision logged to .tack/decisions.md.",
+                },
+            ],
+        };
+    });
+    server.registerTool("log_agent_note", {
+        description: "Append an agent note into .tack/_notes.ndjson for future handoffs.",
+        inputSchema: z.object({
+            type: z.enum(AGENT_NOTE_TYPES),
+            message: z.string().min(1),
+            actor: z.string().optional(),
+            related_files: z.array(z.string()).optional(),
+        }),
+    }, async (args) => {
+        const actor = args.actor && args.actor.trim().length > 0 ? args.actor : "user";
+        const ok = addNote({
+            type: args.type,
+            message: args.message,
+            actor,
+            related_files: args.related_files,
+        });
+        const text = ok
+            ? "Agent note appended to .tack/_notes.ndjson."
+            : "Failed to append agent note to .tack/_notes.ndjson.";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text,
+                },
+            ],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+main();

package/dist/plain/colors.d.ts

@@ -0,0 +1,5 @@
+export declare function green(text: string): string;
+export declare function red(text: string): string;
+export declare function blue(text: string): string;
+export declare function gray(text: string): string;
+export declare function bold(text: string): string;

package/dist/plain/colors.js

@@ -0,0 +1,16 @@
+import pc from "picocolors";
+export function green(text) {
+    return pc.green(text);
+}
+export function red(text) {
+    return pc.red(text);
+}
+export function blue(text) {
+    return pc.blue(text);
+}
+export function gray(text) {
+    return pc.gray(text);
+}
+export function bold(text) {
+    return pc.bold(text);
+}

package/dist/plain/diff.d.ts

@@ -0,0 +1 @@
+export declare function runDiffPlain(baseBranch: string | undefined): boolean;