tack-cli 0.1.0

package/dist/lib/files.js

@@ -0,0 +1,529 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { createAudit, createEmptySpec } from "./signals.js";
+import { safeLoadYaml } from "./yaml.js";
+import { validateAudit, validateDriftState, validateSpec } from "./validate.js";
+const LEGACY_DIRNAME = "tack";
+const TACK_DIRNAME = ".tack";
+export function projectRoot() {
+    const cwd = path.resolve(process.cwd());
+    let current = cwd;
+    while (true) {
+        if (path.basename(current) === TACK_DIRNAME) {
+            return path.dirname(current);
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return cwd;
+}
+export function findProjectRoot() {
+    return projectRoot();
+}
+function getLegacyTackDir() {
+    return path.resolve(projectRoot(), LEGACY_DIRNAME);
+}
+function getTackDir() {
+    return path.resolve(projectRoot(), TACK_DIRNAME);
+}
+function emitValidationWarnings(file, warnings) {
+    if (warnings.length === 0)
+        return;
+    for (const warning of warnings) {
+        console.warn(`[tack] ${file}: ${warning}`);
+    }
+}
+function migrateLegacyDirIfNeeded() {
+    const legacyDir = getLegacyTackDir();
+    const newDir = getTackDir();
+    if (!fs.existsSync(newDir) && fs.existsSync(legacyDir)) {
+        fs.renameSync(legacyDir, newDir);
+    }
+}
+function migrateMachineFilesIfNeeded() {
+    const mapping = [
+        { oldName: "audit.yaml", newName: "_audit.yaml" },
+        { oldName: "drift.yaml", newName: "_drift.yaml" },
+        { oldName: "logs.ndjson", newName: "_logs.ndjson" },
+    ];
+    const dir = getTackDir();
+    if (!fs.existsSync(dir))
+        return;
+    for (const file of mapping) {
+        const oldPath = path.join(dir, file.oldName);
+        const newPath = path.join(dir, file.newName);
+        if (fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
+            fs.renameSync(oldPath, newPath);
+        }
+    }
+}
+function assertInsideTackDir(filepath) {
+    const resolved = path.resolve(filepath);
+    const tackDir = getTackDir();
+    if (!resolved.startsWith(tackDir + path.sep) && resolved !== tackDir) {
+        throw new Error(`WRITE BLOCKED: "${resolved}" is outside /.tack/ directory. ` +
+            `Tack only writes to ${tackDir}. This is a bug — report it.`);
+    }
+}
+export function writeSafe(filepath, content) {
+    assertInsideTackDir(filepath);
+    const dir = path.dirname(filepath);
+    try {
+        if (!fs.existsSync(dir)) {
+            assertInsideTackDir(dir);
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filepath, content, "utf-8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("EACCES") || message.includes("EPERM")) {
+            throw new Error(`Permission denied writing ${filepath}. Check .tack permissions.`);
+        }
+        if (message.includes("ENOSPC")) {
+            throw new Error(`Disk full while writing ${filepath}.`);
+        }
+        throw new Error(`Failed to write ${filepath}: ${message}`);
+    }
+}
+export function appendSafe(filepath, content) {
+    assertInsideTackDir(filepath);
+    const dir = path.dirname(filepath);
+    try {
+        if (!fs.existsSync(dir)) {
+            assertInsideTackDir(dir);
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.appendFileSync(filepath, content, "utf-8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("EACCES") || message.includes("EPERM")) {
+            throw new Error(`Permission denied writing ${filepath}. Check .tack permissions.`);
+        }
+        if (message.includes("ENOSPC")) {
+            throw new Error(`Disk full while writing ${filepath}.`);
+        }
+        throw new Error(`Failed to append ${filepath}: ${message}`);
+    }
+}
+export function ensureTackDir() {
+    migrateLegacyDirIfNeeded();
+    const tackDir = getTackDir();
+    if (!fs.existsSync(tackDir)) {
+        fs.mkdirSync(tackDir, { recursive: true });
+    }
+    migrateMachineFilesIfNeeded();
+    const handoffsDir = path.join(tackDir, "handoffs");
+    if (!fs.existsSync(handoffsDir)) {
+        fs.mkdirSync(handoffsDir, { recursive: true });
+    }
+}
+export function readFile(filepath) {
+    try {
+        return fs.readFileSync(path.resolve(projectRoot(), filepath), "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+export function fileExists(filepath) {
+    return fs.existsSync(path.resolve(projectRoot(), filepath));
+}
+export function readJson(filepath) {
+    const content = readFile(filepath);
+    if (!content)
+        return null;
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+export function readYaml(filepath) {
+    const resolved = path.resolve(projectRoot(), filepath);
+    const { data, error } = safeLoadYaml(resolved, null);
+    if (error)
+        return null;
+    return data;
+}
+export function listProjectFiles(dir) {
+    const base = projectRoot();
+    const root = path.resolve(base, dir ?? ".");
+    const pkg = readJson("package.json");
+    const isTackRepo = pkg?.name === "tack" || pkg?.name === "tack-cli";
+    const ignore = new Set([
+        "node_modules",
+        ".git",
+        "tack",
+        ".tack",
+        "dist",
+        "build",
+        ".next",
+        ".cache",
+        ".svelte-kit",
+        ".output",
+        ".nuxt",
+        ".vercel",
+        ".netlify",
+        "coverage",
+        "__pycache__",
+        "venv",
+        ".venv",
+        "env",
+        "site-packages",
+    ]);
+    const results = [];
+    const selfNoisePrefixes = [
+        "src/detectors/",
+        "src/engine/",
+        "src/plain/",
+        "src/ui/",
+        "tests/",
+    ];
+    function shouldSkipFile(relativePath) {
+        if (!isTackRepo)
+            return false;
+        const normalized = relativePath.replace(/\\/g, "/");
+        if (selfNoisePrefixes.some((prefix) => normalized.startsWith(prefix)))
+            return true;
+        if (normalized === "src/index.tsx" || normalized === "src/App.tsx")
+            return true;
+        if (normalized.endsWith(".md"))
+            return true;
+        return false;
+    }
+    function walk(current) {
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (ignore.has(entry.name))
+                continue;
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                const rel = path.relative(base, full);
+                if (shouldSkipFile(rel))
+                    continue;
+                results.push(rel);
+            }
+        }
+    }
+    walk(root);
+    return results;
+}
+export function grepFiles(files, pattern, maxResults = 50) {
+    const matches = [];
+    for (const file of files) {
+        if (matches.length >= maxResults)
+            break;
+        try {
+            const stat = fs.statSync(path.resolve(projectRoot(), file));
+            if (stat.size > 1024 * 1024)
+                continue; // Skip files larger than 1MB
+        }
+        catch {
+            continue;
+        }
+        const content = readFile(file);
+        if (!content)
+            continue;
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i += 1) {
+            if (matches.length >= maxResults)
+                break;
+            const line = lines[i];
+            if (line.length > 2000)
+                continue; // Skip exceptionally long lines to prevent ReDoS
+            if (pattern.test(line)) {
+                matches.push({ file, line: i + 1, content: line.trim() });
+            }
+        }
+    }
+    return matches;
+}
+export function specPath() {
+    migrateLegacyDirIfNeeded();
+    return path.join(getTackDir(), "spec.yaml");
+}
+export function readSpec() {
+    migrateLegacyDirIfNeeded();
+    return readSpecWithError().spec;
+}
+export function readSpecWithError() {
+    migrateLegacyDirIfNeeded();
+    const { data, error } = safeLoadYaml(specPath(), null);
+    if (error)
+        return { spec: null, error };
+    const validated = validateSpec(data, projectRoot());
+    emitValidationWarnings("spec.yaml", validated.warnings);
+    return { spec: validated.data, error: null };
+}
+export function writeSpec(spec) {
+    const content = yaml.dump(spec, {
+        lineWidth: 120,
+        noRefs: true,
+        sortKeys: false,
+        quotingType: '"',
+    });
+    writeSafe(specPath(), content);
+}
+export function specExists() {
+    migrateLegacyDirIfNeeded();
+    return fileExists(specPath());
+}
+export function auditPath() {
+    ensureTackDir();
+    return path.join(getTackDir(), "_audit.yaml");
+}
+export function readAudit() {
+    migrateLegacyDirIfNeeded();
+    migrateMachineFilesIfNeeded();
+    const raw = readYaml(auditPath());
+    const validated = validateAudit(raw);
+    emitValidationWarnings("_audit.yaml", validated.warnings);
+    return validated.data;
+}
+export function writeAudit(audit) {
+    const content = yaml.dump(audit, {
+        lineWidth: 120,
+        noRefs: true,
+        sortKeys: false,
+    });
+    writeSafe(auditPath(), content);
+}
+export function driftPath() {
+    ensureTackDir();
+    return path.join(getTackDir(), "_drift.yaml");
+}
+export function readDrift() {
+    migrateLegacyDirIfNeeded();
+    migrateMachineFilesIfNeeded();
+    const raw = readYaml(driftPath());
+    const validated = validateDriftState(raw);
+    emitValidationWarnings("_drift.yaml", validated.warnings);
+    return validated.data;
+}
+export function writeDrift(state) {
+    const content = yaml.dump(state, {
+        lineWidth: 120,
+        noRefs: true,
+        sortKeys: false,
+    });
+    writeSafe(driftPath(), content);
+}
+export function logsPath() {
+    ensureTackDir();
+    return path.join(getTackDir(), "_logs.ndjson");
+}
+export function notesPath() {
+    ensureTackDir();
+    return path.join(getTackDir(), "_notes.ndjson");
+}
+export function contextPath() {
+    return path.join(getTackDir(), "context.md");
+}
+export function goalsPath() {
+    return path.join(getTackDir(), "goals.md");
+}
+export function assumptionsPath() {
+    return path.join(getTackDir(), "assumptions.md");
+}
+export function openQuestionsPath() {
+    return path.join(getTackDir(), "open_questions.md");
+}
+export function decisionsPath() {
+    return path.join(getTackDir(), "decisions.md");
+}
+export function implementationStatusPath() {
+    return path.join(getTackDir(), "implementation_status.md");
+}
+export function contextIndexPath() {
+    return path.join(getTackDir(), "context_index.md");
+}
+export function verificationPath() {
+    return path.join(getTackDir(), "verification.md");
+}
+export function handoffsDirPath() {
+    return path.join(getTackDir(), "handoffs");
+}
+export function handoffMarkdownPath(timestampId) {
+    return path.join(handoffsDirPath(), `${timestampId}.md`);
+}
+export function handoffJsonPath(timestampId) {
+    return path.join(handoffsDirPath(), `${timestampId}.json`);
+}
+function contextTemplates() {
+    return [
+        {
+            name: "context.md",
+            path: contextPath(),
+            content: [
+                "# Context",
+                "",
+                "## North Star",
+                "- Keep this project aligned with its declared architecture.",
+                "",
+                "## Current Focus",
+                "- Define immediate priorities for this project.",
+                "",
+                "## Notes",
+                "- Add grounded context only (no speculative narrative).",
+                "",
+            ].join("\n"),
+        },
+        {
+            name: "goals.md",
+            path: goalsPath(),
+            content: [
+                "# Goals",
+                "",
+                "## Goals",
+                "- ",
+                "",
+                "## Non-Goals",
+                "- ",
+                "",
+            ].join("\n"),
+        },
+        {
+            name: "assumptions.md",
+            path: assumptionsPath(),
+            content: [
+                "# Assumptions",
+                "",
+                "- [open] ",
+                "",
+            ].join("\n"),
+        },
+        {
+            name: "open_questions.md",
+            path: openQuestionsPath(),
+            content: [
+                "# Open Questions",
+                "",
+                "- [open] ",
+                "",
+            ].join("\n"),
+        },
+        {
+            name: "decisions.md",
+            path: decisionsPath(),
+            content: [
+                "# Decisions",
+                "",
+                "- [YYYY-MM-DD] Decision title — reason",
+                "",
+            ].join("\n"),
+        },
+        {
+            name: "implementation_status.md",
+            path: implementationStatusPath(),
+            content: [
+                "# Implementation Status",
+                "",
+                "Binary, source-anchored claims only. If you can't anchor it, mark it as `unknown` or `pending`.",
+                "",
+                "Format:",
+                "",
+                "```text",
+                "- log_rotation: implemented (src/lib/logger.ts, src/lib/ndjson.ts)",
+                "- compaction_engine: pending",
+                "- some_feature: unknown",
+                "```",
+                "",
+                "Start here:",
+                "- ",
+                "",
+            ].join("\n"),
+        },
+        {
+            name: "context_index.md",
+            path: contextIndexPath(),
+            content: [
+                "# Context Index",
+                "",
+                "This file maps task types to the minimal `.tack/` docs needed to complete them.",
+                "",
+                "## Suggested retrieval scopes",
+                "",
+                "- agent_handoff: context.md, goals.md, open_questions.md, decisions.md, implementation_status.md, spec.yaml, _audit.yaml, _drift.yaml",
+                "- architecture_guardrails: spec.yaml, decisions.md, implementation_status.md",
+                "- product_pitch: context.md, goals.md, decisions.md",
+                "",
+            ].join("\n"),
+        },
+        {
+            name: "verification.md",
+            path: verificationPath(),
+            content: [
+                "# Validation / Verification",
+                "",
+                "Commands or checks to run after applying changes (e.g. tests, linters, health checks).",
+                "Tack does not execute these; they are suggestions for humans or external tools.",
+                "",
+                "- ",
+                "",
+            ].join("\n"),
+        },
+    ];
+}
+export function ensureContextTemplates() {
+    ensureTackDir();
+    const templates = contextTemplates();
+    for (const template of templates) {
+        if (!fileExists(template.path)) {
+            writeSafe(template.path, template.content);
+        }
+    }
+}
+export function ensureTackIntegrity() {
+    ensureTackDir();
+    migrateMachineFilesIfNeeded();
+    const repaired = [];
+    if (!specExists()) {
+        return { repaired };
+    }
+    const templates = contextTemplates();
+    for (const template of templates) {
+        if (!fileExists(template.path)) {
+            writeSafe(template.path, template.content);
+            repaired.push(template.name);
+        }
+    }
+    if (!fileExists(driftPath())) {
+        writeDrift({ items: [] });
+        repaired.push("_drift.yaml");
+    }
+    if (!fileExists(notesPath())) {
+        writeSafe(notesPath(), "");
+        repaired.push("_notes.ndjson");
+    }
+    if (!fileExists(logsPath())) {
+        writeSafe(logsPath(), "");
+        repaired.push("_logs.ndjson");
+    }
+    if (!fileExists(auditPath())) {
+        writeAudit(createAudit([]));
+        repaired.push("_audit.yaml");
+    }
+    return { repaired };
+}
+export function seedSpecIfMissing() {
+    if (specExists())
+        return false;
+    const projectName = path.basename(projectRoot()) || "my-project";
+    writeSpec(createEmptySpec(projectName));
+    return true;
+}

package/dist/lib/git.d.ts

@@ -0,0 +1,9 @@
+export declare function isGitRepo(): boolean;
+export declare function hasCommits(): boolean;
+export declare function getCurrentBranch(): string;
+export declare function getShortRef(): string;
+export declare function getLatestCommitSubject(): string;
+export declare function getMergeBase(refA: string, refB?: string): string | null;
+export declare function readFileAtRef(ref: string, filepath: string): string | null;
+export declare function filterChangedPaths(lines: string[]): string[];
+export declare function getChangedFiles(base?: string): string[];

package/dist/lib/git.js

@@ -0,0 +1,96 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import * as path from "node:path";
+import { projectRoot } from "./files.js";
+const GIT_TIMEOUT_MS = 10_000;
+function gitExec(args) {
+    try {
+        const output = execFileSync("git", args, {
+            cwd: projectRoot(),
+            encoding: "utf-8",
+            timeout: GIT_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return { ok: true, value: output.trim() };
+    }
+    catch {
+        return { ok: false, value: "" };
+    }
+}
+export function isGitRepo() {
+    return gitExec(["rev-parse", "--is-inside-work-tree"]).ok;
+}
+export function hasCommits() {
+    return gitExec(["rev-parse", "HEAD"]).ok;
+}
+export function getCurrentBranch() {
+    const result = gitExec(["branch", "--show-current"]);
+    return result.ok && result.value ? result.value : "unknown";
+}
+export function getShortRef() {
+    const result = gitExec(["rev-parse", "--short", "HEAD"]);
+    return result.ok && result.value ? result.value : "unknown";
+}
+export function getLatestCommitSubject() {
+    const result = gitExec(["log", "-1", "--format=%s"]);
+    return result.ok && result.value ? result.value : "";
+}
+export function getMergeBase(refA, refB = "HEAD") {
+    const result = gitExec(["merge-base", refB, refA]);
+    return result.ok && result.value ? result.value : null;
+}
+export function readFileAtRef(ref, filepath) {
+    const normalizedPath = filepath.replace(/\\/g, "/");
+    const result = gitExec(["show", `${ref}:${normalizedPath}`]);
+    return result.ok && result.value ? result.value : null;
+}
+function dedupeAndFilter(lines) {
+    const seen = new Set();
+    const root = projectRoot();
+    return lines
+        .map((line) => line.trim())
+        .filter((line) => {
+        if (!line)
+            return false;
+        if (line.startsWith(".tack/") || line.startsWith(".tack\\"))
+            return false;
+        if (seen.has(line))
+            return false;
+        const absolute = path.resolve(root, line);
+        if (existsSync(absolute)) {
+            try {
+                if (!statSync(absolute).isFile())
+                    return false;
+            }
+            catch {
+                return false;
+            }
+        }
+        seen.add(line);
+        return true;
+    });
+}
+export function filterChangedPaths(lines) {
+    return dedupeAndFilter(lines);
+}
+export function getChangedFiles(base = "HEAD~1") {
+    if (!isGitRepo())
+        return [];
+    if (!hasCommits()) {
+        const staged = gitExec(["diff", "--cached", "--name-only"]);
+        const unstaged = gitExec(["diff", "--name-only"]);
+        const untracked = gitExec(["ls-files", "--others", "--exclude-standard"]);
+        const all = [
+            ...(staged.ok ? staged.value.split("\n") : []),
+            ...(unstaged.ok ? unstaged.value.split("\n") : []),
+            ...(untracked.ok ? untracked.value.split("\n") : []),
+        ];
+        return dedupeAndFilter(all);
+    }
+    const diffResult = gitExec(["diff", "--name-only", base]);
+    if (diffResult.ok) {
+        return dedupeAndFilter(diffResult.value.split("\n"));
+    }
+    const fallback = gitExec(["ls-files"]);
+    return fallback.ok ? dedupeAndFilter(fallback.value.split("\n")) : [];
+}

package/dist/lib/logger.d.ts

@@ -0,0 +1,3 @@
+import type { LogEvent, LogEventInput } from "./signals.js";
+export declare function log(event: LogEventInput): void;
+export declare function readRecentLogs<T = LogEvent>(limit?: number): T[];

package/dist/lib/logger.js

@@ -0,0 +1,21 @@
+import { appendSafe, logsPath } from "./files.js";
+import { rotateNdjsonFile, safeReadNdjson } from "./ndjson.js";
+const LOG_MAX_BYTES = 5 * 1024 * 1024;
+const LOG_KEEP_LINES = 5000;
+export function log(event) {
+    const entry = {
+        ts: new Date().toISOString(),
+        ...event,
+    };
+    const filepath = logsPath();
+    try {
+        rotateNdjsonFile(filepath, LOG_MAX_BYTES, LOG_KEEP_LINES);
+        appendSafe(filepath, `${JSON.stringify(entry)}\n`);
+    }
+    catch {
+        return;
+    }
+}
+export function readRecentLogs(limit = 50) {
+    return safeReadNdjson(logsPath(), limit);
+}

package/dist/lib/ndjson.d.ts

@@ -0,0 +1,2 @@
+export declare function safeReadNdjson<T = Record<string, unknown>>(filepath: string, limit?: number): T[];
+export declare function rotateNdjsonFile(filepath: string, maxBytes: number, keepLines: number): void;