@spikedpunch/align-cli 0.1.0

package/dist/telemetry/recorder.js

@@ -0,0 +1,61 @@
+import { serializeTelemetryEvent, TELEMETRY_SCHEMA_VERSION } from '@spikedpunch/align-core';
+import { appendTelemetryLine } from '../align-dir.js';
+import { resolveTelemetryEnabled } from './resolve.js';
+import { ALIGN_VERSION, TELEMETRY_SESSION_ID } from './process-context.js';
+/**
+ * The ONE wrapper that builds the envelope and writes it (IMPLEMENTATION_PLAN.md's telemetry spec:
+ * "prefer ONE wrapper... over scattering emit calls"). Every command that emits telemetry
+ * constructs exactly one of these (via `program.ts`'s `buildTelemetryRecorder`) and calls
+ * `.record()` with its own domain event — no command touches `appendTelemetryLine` or builds an
+ * envelope itself.
+ */
+export class TelemetryRecorder {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    get enabled() {
+        return this.options.enabled;
+    }
+    record(event, opts = {}) {
+        if (!this.options.enabled)
+            return;
+        const envelope = {
+            schemaVersion: TELEMETRY_SCHEMA_VERSION,
+            sessionId: this.options.sessionId,
+            alignVersion: this.options.alignVersion,
+            ...(opts.rulesetIrHash !== undefined ? { rulesetIrHash: opts.rulesetIrHash } : {}),
+            ts: this.options.now(),
+            command: this.options.command,
+            event,
+        };
+        appendTelemetryLine(this.options.rootDir, serializeTelemetryEvent(envelope), this.options.jsonlPathOverride);
+    }
+}
+/** OFF-by-default (IMPLEMENTATION_PLAN.md): a recorder constructed with `enabled: false` never
+ * calls `appendTelemetryLine` — `.record()` is a no-op, so `.align/telemetry.jsonl` is never even
+ * created, let alone written to. */
+export function createDisabledTelemetryRecorder(rootDir, command) {
+    return new TelemetryRecorder({ rootDir, enabled: false, sessionId: '', alignVersion: '', command, now: Date.now });
+}
+/**
+ * The composition-root factory every command calls (`program.ts` is the "central wiring point" —
+ * it resolves the pre-config half of the precedence via CLI flags/`ALIGN_TELEMETRY`, then each
+ * command finishes the resolution once it has loaded `align.config.ts`'s own `telemetry` export
+ * and calls this). `sessionId`/`alignVersion` always come from the shared process-wide constants
+ * (`process-context.ts`) — never re-derived per call — so every event in one `align` invocation,
+ * across however many commands ran, shares the same session id.
+ */
+export function createTelemetryRecorder(rootDir, command, preConfig, configTelemetry, jsonlPathOverride) {
+    const enabled = resolveTelemetryEnabled(preConfig, configTelemetry);
+    return new TelemetryRecorder({
+        rootDir,
+        enabled,
+        sessionId: TELEMETRY_SESSION_ID,
+        alignVersion: ALIGN_VERSION,
+        command,
+        now: Date.now,
+        ...(jsonlPathOverride !== undefined ? { jsonlPathOverride } : {}),
+    });
+}
+//# sourceMappingURL=recorder.js.map

package/dist/telemetry/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../src/telemetry/recorder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAuB,MAAM,yBAAyB,CAAC;AACjH,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAgB3E;;;;;;GAMG;AACH,MAAM,OAAO,iBAAiB;IACC;IAA7B,YAA6B,OAAiC;QAAjC,YAAO,GAAP,OAAO,CAA0B;IAAG,CAAC;IAElE,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED,MAAM,CAAC,KAAqB,EAAE,OAA4C,EAAE;QAC1E,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO;YAAE,OAAO;QAClC,MAAM,QAAQ,GAAG;YACf,aAAa,EAAE,wBAAwB;YACvC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS;YACjC,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,YAAY;YACvC,GAAG,CAAC,IAAI,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClF,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE;YACtB,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;YAC7B,KAAK;SACN,CAAC;QACF,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,uBAAuB,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC/G,CAAC;CACF;AAED;;oCAEoC;AACpC,MAAM,UAAU,+BAA+B,CAAC,OAAe,EAAE,OAAe;IAC9E,OAAO,IAAI,iBAAiB,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;AACrH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAe,EACf,OAAe,EACf,SAA8B,EAC9B,eAAoC,EACpC,iBAA0B;IAE1B,MAAM,OAAO,GAAG,uBAAuB,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IACpE,OAAO,IAAI,iBAAiB,CAAC;QAC3B,OAAO;QACP,OAAO;QACP,SAAS,EAAE,oBAAoB;QAC/B,YAAY,EAAE,aAAa;QAC3B,OAAO;QACP,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,GAAG,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClE,CAAC,CAAC;AACL,CAAC"}

package/dist/telemetry/resolve.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `ALIGN_TELEMETRY=1` (env) OR `telemetry: true` (align.config.ts) OR `--telemetry` (flag)
+ * enables telemetry; `--no-telemetry` overrides ALL of them. OFF by default
+ * (IMPLEMENTATION_PLAN.md's telemetry Design Reserve entry).
+ *
+ * Split into two steps because the flag/env precedence is decidable before `align.config.ts` is
+ * ever loaded (and `align check --untrusted` never loads it at all, ADR 014) while the config-file
+ * toggle only exists once a command has called `loadConfig`. `resolveTelemetryPreConfig` returns
+ * `undefined` exactly when the decision must defer to `config.telemetry`.
+ */
+export interface TelemetryCliFlags {
+    /** `--telemetry` / `--no-telemetry`, straight from commander's `opts.telemetry` — always passed
+     * explicitly (not `?:`) so a call site's `{ telemetry: opts.telemetry }` never trips
+     * `exactOptionalPropertyTypes` just because commander's own type is `boolean | undefined`. */
+    readonly telemetry: boolean | undefined;
+}
+export declare function resolveTelemetryPreConfig(flags: TelemetryCliFlags, env?: NodeJS.ProcessEnv): boolean | undefined;
+export declare function resolveTelemetryEnabled(preConfig: boolean | undefined, configTelemetry: boolean | undefined): boolean;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/telemetry/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/telemetry/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC;;kGAE8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,GAAG,SAAS,CAQ7H;AAED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,EAAE,eAAe,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAGrH"}

package/dist/telemetry/resolve.js

@@ -0,0 +1,18 @@
+export function resolveTelemetryPreConfig(flags, env = process.env) {
+    // Commander's negatable-option pairing (`--telemetry` / `--no-telemetry` sharing one `telemetry`
+    // property) already collapses "--no-telemetry was passed" down to `flags.telemetry === false` —
+    // that's the one case that must win over everything else, checked first.
+    if (flags.telemetry === false)
+        return false;
+    if (flags.telemetry === true)
+        return true;
+    if (env['ALIGN_TELEMETRY'] === '1')
+        return true;
+    return undefined;
+}
+export function resolveTelemetryEnabled(preConfig, configTelemetry) {
+    if (preConfig !== undefined)
+        return preConfig;
+    return configTelemetry === true;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/telemetry/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/telemetry/resolve.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,yBAAyB,CAAC,KAAwB,EAAE,MAAyB,OAAO,CAAC,GAAG;IACtG,iGAAiG;IACjG,gGAAgG;IAChG,yEAAyE;IACzE,IAAI,KAAK,CAAC,SAAS,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,GAAG,CAAC,iBAAiB,CAAC,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAChD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,SAA8B,EAAE,eAAoC;IAC1G,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,OAAO,eAAe,KAAK,IAAI,CAAC;AAClC,CAAC"}

package/dist/telemetry/ruleset-hash.d.ts

@@ -0,0 +1,10 @@
+import { type RulesetIR } from '@spikedpunch/align-core';
+/**
+ * `rulesetIrHash` (the envelope's cross-session-comparability refinement) — reuses the exact
+ * content-hash function `.align/rules.lock.json`'s divergence detection already computes with
+ * (`sha256Hex`, `packages/core/src/build/hash.ts`) rather than inventing a second hashing scheme.
+ * `RulesetIR` is always zod-parsed JSON with a fixed field order (ADR 002: no function-valued
+ * fields, portable), so `JSON.stringify` is deterministic for a given ruleset content.
+ */
+export declare function computeRulesetIrHash(ruleset: RulesetIR): string;
+//# sourceMappingURL=ruleset-hash.d.ts.map

package/dist/telemetry/ruleset-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruleset-hash.d.ts","sourceRoot":"","sources":["../../src/telemetry/ruleset-hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,CAE/D"}

package/dist/telemetry/ruleset-hash.js

@@ -0,0 +1,12 @@
+import { sha256Hex } from '@spikedpunch/align-core';
+/**
+ * `rulesetIrHash` (the envelope's cross-session-comparability refinement) — reuses the exact
+ * content-hash function `.align/rules.lock.json`'s divergence detection already computes with
+ * (`sha256Hex`, `packages/core/src/build/hash.ts`) rather than inventing a second hashing scheme.
+ * `RulesetIR` is always zod-parsed JSON with a fixed field order (ADR 002: no function-valued
+ * fields, portable), so `JSON.stringify` is deterministic for a given ruleset content.
+ */
+export function computeRulesetIrHash(ruleset) {
+    return sha256Hex(JSON.stringify(ruleset));
+}
+//# sourceMappingURL=ruleset-hash.js.map

package/dist/telemetry/ruleset-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruleset-hash.js","sourceRoot":"","sources":["../../src/telemetry/ruleset-hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAkB;IACrD,OAAO,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;AAC5C,CAAC"}

package/dist/telemetry/session.d.ts

@@ -0,0 +1,6 @@
+/** One session id per CLI process (IMPLEMENTATION_PLAN.md's cross-session-comparability
+ * refinement) — generated once here and threaded through every event the process emits, never
+ * regenerated mid-process. `randomUUID` is a local, non-network primitive (Node's `node:crypto`),
+ * not a call to any external id service. */
+export declare function generateSessionId(): string;
+//# sourceMappingURL=session.d.ts.map

package/dist/telemetry/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/telemetry/session.ts"],"names":[],"mappings":"AAEA;;;4CAG4C;AAC5C,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/telemetry/session.js

@@ -0,0 +1,9 @@
+import { randomUUID } from 'node:crypto';
+/** One session id per CLI process (IMPLEMENTATION_PLAN.md's cross-session-comparability
+ * refinement) — generated once here and threaded through every event the process emits, never
+ * regenerated mid-process. `randomUUID` is a local, non-network primitive (Node's `node:crypto`),
+ * not a call to any external id service. */
+export function generateSessionId() {
+    return randomUUID();
+}
+//# sourceMappingURL=session.js.map

package/dist/telemetry/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/telemetry/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;4CAG4C;AAC5C,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC"}

package/dist/telemetry/violations.d.ts

@@ -0,0 +1,10 @@
+import { type TelemetryEvent, type Violation } from '@spikedpunch/align-core';
+/**
+ * `violation-appeared`/`violation-resolved` (IMPLEMENTATION_PLAN.md's telemetry spec): diffs the
+ * current check's non-baselined violation set against `.align/telemetry-state.json` (the previous
+ * check's set), then persists the new set for the next invocation. Only called when telemetry is
+ * enabled — a disabled run must never touch `telemetry-state.json` (OFF-by-default writes
+ * nothing), so gating happens at the call site (`commands/check.ts`), not here.
+ */
+export declare function computeAndPersistViolationTransitions(rootDir: string, violations: readonly Violation[]): readonly TelemetryEvent[];
+//# sourceMappingURL=violations.d.ts.map

package/dist/telemetry/violations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"violations.d.ts","sourceRoot":"","sources":["../../src/telemetry/violations.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6C,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGzH;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,cAAc,EAAE,CA0BlI"}

package/dist/telemetry/violations.js

@@ -0,0 +1,36 @@
+import { diffViolationState, telemetryStateEntryOf } from '@spikedpunch/align-core';
+import { readTelemetryState, writeTelemetryState } from '../align-dir.js';
+/**
+ * `violation-appeared`/`violation-resolved` (IMPLEMENTATION_PLAN.md's telemetry spec): diffs the
+ * current check's non-baselined violation set against `.align/telemetry-state.json` (the previous
+ * check's set), then persists the new set for the next invocation. Only called when telemetry is
+ * enabled — a disabled run must never touch `telemetry-state.json` (OFF-by-default writes
+ * nothing), so gating happens at the call site (`commands/check.ts`), not here.
+ */
+export function computeAndPersistViolationTransitions(rootDir, violations) {
+    const previous = readTelemetryState(rootDir).violations;
+    const current = violations.map((v) => telemetryStateEntryOf(v));
+    const diff = diffViolationState(previous, current);
+    writeTelemetryState(rootDir, { violations: current });
+    const events = [];
+    for (const e of diff.appeared) {
+        events.push({
+            kind: 'violation-appeared',
+            ruleId: e.ruleId,
+            file: e.file,
+            violationFingerprint: e.fingerprint,
+            ...(e.component !== undefined ? { component: e.component } : {}),
+        });
+    }
+    for (const e of diff.resolved) {
+        events.push({
+            kind: 'violation-resolved',
+            ruleId: e.ruleId,
+            file: e.file,
+            violationFingerprint: e.fingerprint,
+            ...(e.component !== undefined ? { component: e.component } : {}),
+        });
+    }
+    return events;
+}
+//# sourceMappingURL=violations.js.map

package/dist/telemetry/violations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"violations.js","sourceRoot":"","sources":["../../src/telemetry/violations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAuC,MAAM,yBAAyB,CAAC;AACzH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,UAAU,qCAAqC,CAAC,OAAe,EAAE,UAAgC;IACrG,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC;IACxD,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,kBAAkB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACnD,mBAAmB,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IAEtD,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,oBAAoB,EAAE,CAAC,CAAC,WAAW;YACnC,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,oBAAoB,EAAE,CAAC,CAAC,WAAW;YACnC,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@spikedpunch/align-cli",
+  "version": "0.1.0",
+  "description": "align CLI — an architecture-conformance verification oracle for LLM coding agents, with a built-in MCP server.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SpikedPunchVictim/align",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "align",
+    "architecture",
+    "conformance",
+    "cli",
+    "mcp",
+    "model-context-protocol",
+    "dependency-graph",
+    "static-analysis"
+  ],
+  "type": "module",
+  "bin": {
+    "align": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "commander": "^12.1.0",
+    "zod": "^3.23.8",
+    "@spikedpunch/align-plugin-typescript": "0.1.0",
+    "@spikedpunch/align-core": "0.1.0",
+    "@spikedpunch/align-agent": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4",
+    "@types/node": "^22.9.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}