tack-cli 0.1.0

package/dist/engine/status.d.ts

@@ -0,0 +1,10 @@
+import type { ProjectStatus, Signal, Spec, SpecDiff, DriftState } from "../lib/signals.js";
+export type StatusResult = {
+    spec: Spec;
+    diff: SpecDiff;
+    drift: DriftState;
+    status: ProjectStatus;
+};
+export declare function buildProjectStatus(spec: Spec, diff: SpecDiff, drift: DriftState): ProjectStatus;
+export declare function computeStatusFromSignals(signals: Signal[]): StatusResult | null;
+export declare function runStatusScan(): StatusResult | null;

package/dist/engine/status.js

@@ -0,0 +1,46 @@
+import { runAllDetectors } from "../detectors/index.js";
+import { compareSpec } from "./compareSpec.js";
+import { computeDrift } from "./computeDrift.js";
+import { readSpec, writeAudit } from "../lib/files.js";
+import { createAudit } from "../lib/signals.js";
+import { log } from "../lib/logger.js";
+export function buildProjectStatus(spec, diff, drift) {
+    const unresolved = drift.items.filter((i) => i.status === "unresolved");
+    const driftItems = unresolved.map((item) => ({
+        system: item.system ?? item.risk ?? item.type,
+        message: item.signal,
+    }));
+    return {
+        name: spec.project,
+        health: unresolved.length > 0 ? "drift" : "aligned",
+        driftCount: unresolved.length,
+        driftItems,
+        lastScan: new Date().toISOString(),
+    };
+}
+export function computeStatusFromSignals(signals) {
+    const startedAt = Date.now();
+    const spec = readSpec();
+    if (!spec)
+        return null;
+    const audit = createAudit(signals);
+    writeAudit(audit);
+    const diff = compareSpec(signals, spec);
+    const { state } = computeDrift(diff);
+    log({
+        event: "scan",
+        systems_detected: signals.filter((s) => s.category === "system").length,
+        drift_items: state.items.filter((item) => item.status === "unresolved").length,
+        duration_ms: Date.now() - startedAt,
+    });
+    return {
+        spec,
+        diff,
+        drift: state,
+        status: buildProjectStatus(spec, diff, state),
+    };
+}
+export function runStatusScan() {
+    const { signals } = runAllDetectors();
+    return computeStatusFromSignals(signals);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { render } from "ink";
+import minimist from "minimist";
+import { App } from "./App.js";
+import { usePlainOutput } from "./lib/tty.js";
+import { runStatusScan } from "./engine/status.js";
+import { printStatusPlain } from "./plain/status.js";
+import { generateHandoff } from "./engine/handoff.js";
+import { printHandoffPlain } from "./plain/handoff.js";
+import { runInitPlain } from "./plain/init.js";
+import { runWatchPlain } from "./plain/watch.js";
+import { log, readRecentLogs } from "./lib/logger.js";
+import { appendDecision, normalizeDecisionActor, readDecisionsMarkdown } from "./engine/decisions.js";
+import { ensureTackIntegrity } from "./lib/files.js";
+import { fileExists } from "./lib/files.js";
+import { readSpecWithError, specExists } from "./lib/files.js";
+import { printNotes, addNotePlain } from "./plain/notes.js";
+import { compactNotes } from "./lib/notes.js";
+import { runDiffPlain } from "./plain/diff.js";
+const ASCII_LOGO = `
+ ████████╗ █████╗  ██████╗██╗  ██╗
+ ╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝
+    ██║   ███████║██║     █████╔╝
+    ██║   ██╔══██║██║     ██╔═██╗
+    ██║   ██║  ██║╚██████╗██║  ██╗
+    ╚═╝   ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝
+`;
+import updateNotifier from "update-notifier";
+import { readFileSync } from "node:fs";
+const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+updateNotifier({ pkg }).notify();
+const args = minimist(process.argv.slice(2));
+if (args.version || args.v) {
+    // eslint-disable-next-line no-console
+    console.log(pkg.version);
+    process.exit(0);
+}
+const rawCommand = args._[0];
+const command = rawCommand ?? (fileExists(".tack") ? "watch" : "init");
+const VALID_COMMANDS = ["init", "status", "watch", "handoff", "log", "note", "diff", "mcp", "help"];
+function isValidCommand(value) {
+    return VALID_COMMANDS.includes(value);
+}
+if (command === "help" || args.help || args.h) {
+    // eslint-disable-next-line no-console
+    console.log(`
+${ASCII_LOGO}
+  tack — Architecture drift guard
+
+  Usage:
+    npx tack init [--ink]          Set up spec.yaml from detected architecture
+    npx tack status [--ink]        Run a scan and show current state
+    npx tack watch [--plain]       Persistent watcher with live drift alerts
+    npx tack handoff [--ink]       Generate agent handoff artifacts
+    npx tack log                   View or append decisions
+    npx tack log events [N]        Show last N log events (default 50)
+    npx tack note                  View/add agent notes
+    npx tack diff <base-branch>    Compare architecture vs base branch (plain)
+    npx tack mcp                   Start MCP server (for Cursor / agent integrations)
+    npx tack help                  Show this help text
+
+  Output mode:
+    default: plain output for all commands except watch
+    --ink: force Ink UI for init/status/handoff
+    --plain or TACK_PLAIN=1: force plain output (including watch)
+
+  Files (all in .tack/):
+    spec.yaml     Your declared architecture contract
+    _audit.yaml   Latest detector sweep results
+    _drift.yaml   Current unresolved drift items
+    _logs.ndjson  Append-only event log
+    context.md, goals.md, assumptions.md, open_questions.md
+    handoffs/<ts>.md, handoffs/<ts>.json
+  `);
+    process.exit(0);
+}
+if (!isValidCommand(command)) {
+    // eslint-disable-next-line no-console
+    console.error(`Unknown command: "${command}". Run "npx tack help" for usage.`);
+    process.exit(1);
+}
+const normalizedCommand = command;
+// tack mcp: start the MCP server (stdio). Run from a project root that has .tack/
+if (normalizedCommand === "mcp") {
+    const cwdTack = path.join(process.cwd(), ".tack");
+    if (!existsSync(cwdTack)) {
+        // eslint-disable-next-line no-console
+        console.error("Run `tack mcp` from a project root that contains a .tack/ directory.");
+        process.exit(1);
+    }
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const mcpHere = path.join(dir, "mcp.js");
+    const mcpInDist = path.join(dir, "..", "dist", "mcp.js");
+    const mcpPath = existsSync(mcpHere) ? mcpHere : mcpInDist;
+    if (!existsSync(mcpPath)) {
+        // eslint-disable-next-line no-console
+        console.error("MCP server not found. Run `npm run build` in the tack repo first.");
+        process.exit(1);
+    }
+    const result = spawnSync(process.execPath, [mcpPath], { stdio: "inherit", cwd: process.cwd() });
+    process.exit(result.status ?? 1);
+}
+const forcePlain = usePlainOutput();
+const forceInk = Boolean(args.ink || process.argv.includes("--ink"));
+const shouldUseInk = normalizedCommand === "watch" ? !forcePlain : forceInk && !forcePlain;
+function printFatal(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // eslint-disable-next-line no-console
+    console.error(`✗ ${message}`);
+    process.exit(1);
+}
+if (normalizedCommand === "status" || normalizedCommand === "watch" || normalizedCommand === "handoff") {
+    if (specExists()) {
+        const { error } = readSpecWithError();
+        if (error) {
+            // eslint-disable-next-line no-console
+            console.error(`⚠ ${error}`);
+            // eslint-disable-next-line no-console
+            console.error("Fix .tack/spec.yaml syntax and run again.");
+            process.exit(1);
+        }
+    }
+    let repaired = [];
+    try {
+        repaired = ensureTackIntegrity().repaired;
+    }
+    catch (err) {
+        printFatal(err);
+    }
+    if (repaired.length > 0) {
+        log({ event: "repair", files: repaired });
+        // eslint-disable-next-line no-console
+        console.log(`Repaired .tack integrity: ${repaired.join(", ")}`);
+    }
+}
+if (normalizedCommand === "log") {
+    const sub = args._[1];
+    if (!sub) {
+        // eslint-disable-next-line no-console
+        console.log(readDecisionsMarkdown());
+        process.exit(0);
+    }
+    if (sub === "events") {
+        const rawLimit = args._[2];
+        let limit = 50;
+        if (typeof rawLimit === "string") {
+            const parsed = Number.parseInt(rawLimit, 10);
+            if (Number.isFinite(parsed) && parsed > 0) {
+                limit = parsed;
+            }
+        }
+        const events = readRecentLogs(limit);
+        if (!events.length) {
+            // eslint-disable-next-line no-console
+            console.log("No log events recorded.");
+            process.exit(0);
+        }
+        for (const event of events) {
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify(event));
+        }
+        process.exit(0);
+    }
+    if (sub !== "decision") {
+        // eslint-disable-next-line no-console
+        console.error(`Unknown log subcommand: "${sub}". Use "tack log", "tack log decision", or "tack log events [N]".`);
+        process.exit(1);
+    }
+    const decisionText = args._.slice(2).join(" ").trim();
+    const reasonText = String(args.reason ?? "").trim();
+    if (!decisionText) {
+        // eslint-disable-next-line no-console
+        console.error('Missing decision text. Usage: tack log decision "Decision" --reason "Reason"');
+        process.exit(1);
+    }
+    if (!reasonText) {
+        // eslint-disable-next-line no-console
+        console.error('Missing reason. Usage: tack log decision "Decision" --reason "Reason"');
+        process.exit(1);
+    }
+    try {
+        appendDecision(decisionText, reasonText);
+        log({
+            event: "decision",
+            decision: decisionText,
+            reasoning: reasonText,
+            actor: normalizeDecisionActor(typeof args.actor === "string" ? args.actor : undefined),
+        });
+    }
+    catch (err) {
+        printFatal(err);
+    }
+    // eslint-disable-next-line no-console
+    console.log("Decision logged.");
+    process.exit(0);
+}
+if (normalizedCommand === "note") {
+    const hasMessage = typeof args.message === "string" && args.message.trim().length > 0;
+    const hasClear = args.clear !== undefined;
+    if (hasMessage && hasClear) {
+        // eslint-disable-next-line no-console
+        console.error('Cannot use --message and --clear together. Use either "tack note --message ..." or "tack note --clear N".');
+        process.exit(1);
+    }
+    if (!hasMessage && !hasClear) {
+        const limit = typeof args.limit === "number" ? args.limit : undefined;
+        const type = typeof args.type === "string" ? args.type : undefined;
+        printNotes({ limit, type });
+        process.exit(0);
+    }
+    if (hasMessage) {
+        const type = typeof args.type === "string" ? args.type : "discovered";
+        const actor = typeof args.actor === "string" ? args.actor : "user";
+        const ok = addNotePlain(type, String(args.message), actor);
+        if (ok) {
+            // eslint-disable-next-line no-console
+            console.log("Note added.");
+        }
+        process.exit(ok ? 0 : 1);
+    }
+    if (hasClear) {
+        const raw = args.clear;
+        const days = typeof raw === "number"
+            ? raw
+            : typeof raw === "string"
+                ? Number.parseInt(raw, 10)
+                : NaN;
+        if (!Number.isFinite(days) || days <= 0) {
+            // eslint-disable-next-line no-console
+            console.error('Invalid value for --clear. Expected a positive number of days, e.g. "tack note --clear 30".');
+            process.exit(1);
+        }
+        const archived = compactNotes(days);
+        // eslint-disable-next-line no-console
+        console.log(`Archived ${archived} notes older than ${days} days.`);
+        process.exit(0);
+    }
+}
+if (!shouldUseInk) {
+    if (normalizedCommand === "init") {
+        try {
+            process.exit(runInitPlain() ? 0 : 1);
+        }
+        catch (err) {
+            printFatal(err);
+        }
+    }
+    if (normalizedCommand === "status") {
+        const result = runStatusScan();
+        if (!result) {
+            // eslint-disable-next-line no-console
+            console.error("No spec.yaml found. Run 'tack init' first.");
+            process.exit(1);
+        }
+        printStatusPlain(result.status);
+        process.exit(0);
+    }
+    if (normalizedCommand === "handoff") {
+        try {
+            const generated = generateHandoff();
+            log({
+                event: "handoff",
+                markdown_path: generated.markdownPath,
+                json_path: generated.jsonPath,
+            });
+            printHandoffPlain(generated.markdownPath, generated.jsonPath, generated.report.generated_at);
+            process.exit(0);
+        }
+        catch (err) {
+            printFatal(err);
+        }
+    }
+    if (normalizedCommand === "watch") {
+        try {
+            await runWatchPlain();
+            process.exit(0);
+        }
+        catch (err) {
+            printFatal(err);
+        }
+    }
+    if (normalizedCommand === "diff") {
+        try {
+            const baseBranch = args._[1];
+            const ok = runDiffPlain(baseBranch);
+            process.exit(ok ? 0 : 1);
+        }
+        catch (err) {
+            printFatal(err);
+        }
+    }
+}
+render(_jsx(App, { command: normalizedCommand }));

package/dist/lib/cli.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Default command resolution: no-arg CLI runs init when .tack/ is missing, otherwise watch.
+ */
+export declare function resolveDefaultCommand(raw: string | undefined, tackDirExists: boolean): "init" | "watch" | string;

package/dist/lib/cli.js

@@ -0,0 +1,8 @@
+/**
+ * Default command resolution: no-arg CLI runs init when .tack/ is missing, otherwise watch.
+ */
+export function resolveDefaultCommand(raw, tackDirExists) {
+    if (raw !== undefined && raw !== "")
+        return raw;
+    return tackDirExists ? "watch" : "init";
+}

package/dist/lib/files.d.ts

@@ -0,0 +1,48 @@
+import { type Spec, type Audit, type DriftState } from "./signals.js";
+export declare function projectRoot(): string;
+export declare function findProjectRoot(): string;
+export declare function writeSafe(filepath: string, content: string): void;
+export declare function appendSafe(filepath: string, content: string): void;
+export declare function ensureTackDir(): void;
+export declare function readFile(filepath: string): string | null;
+export declare function fileExists(filepath: string): boolean;
+export declare function readJson<T = unknown>(filepath: string): T | null;
+export declare function readYaml<T = unknown>(filepath: string): T | null;
+export declare function listProjectFiles(dir?: string): string[];
+export declare function grepFiles(files: string[], pattern: RegExp, maxResults?: number): Array<{
+    file: string;
+    line: number;
+    content: string;
+}>;
+export declare function specPath(): string;
+export declare function readSpec(): Spec | null;
+export declare function readSpecWithError(): {
+    spec: Spec | null;
+    error: string | null;
+};
+export declare function writeSpec(spec: Spec): void;
+export declare function specExists(): boolean;
+export declare function auditPath(): string;
+export declare function readAudit(): Audit | null;
+export declare function writeAudit(audit: Audit): void;
+export declare function driftPath(): string;
+export declare function readDrift(): DriftState;
+export declare function writeDrift(state: DriftState): void;
+export declare function logsPath(): string;
+export declare function notesPath(): string;
+export declare function contextPath(): string;
+export declare function goalsPath(): string;
+export declare function assumptionsPath(): string;
+export declare function openQuestionsPath(): string;
+export declare function decisionsPath(): string;
+export declare function implementationStatusPath(): string;
+export declare function contextIndexPath(): string;
+export declare function verificationPath(): string;
+export declare function handoffsDirPath(): string;
+export declare function handoffMarkdownPath(timestampId: string): string;
+export declare function handoffJsonPath(timestampId: string): string;
+export declare function ensureContextTemplates(): void;
+export declare function ensureTackIntegrity(): {
+    repaired: string[];
+};
+export declare function seedSpecIfMissing(): boolean;