@aligndottech/cli 0.5.0 → 0.7.0

package/dist/lib/usage-telemetry.js

@@ -0,0 +1,63 @@
+/**
+ * ALI-403: emit one `cli.command` event per invocation so cloud CLI activation and weekly
+ * retention are countable.
+ *
+ * Cloud mode only. A cloud user is already on an authenticated connection to our gateway, so
+ * an event about a call already being made is not a new phone-home. `--local` users never
+ * contact us and have no tenant, so counting them needs an explicit consent flow and its own
+ * storage (`telemetry_events.tenant_id` is `NOT NULL REFERENCES tenants(id)`).
+ *
+ * Set `ALIGN_TELEMETRY=0` to opt out entirely.
+ */
+export const TELEMETRY_TIMEOUT_MS = 2_000;
+export async function recordCommandUsage(env, command) {
+    if (process.env['ALIGN_TELEMETRY'] === '0')
+        return;
+    // `align local ...` is the explicitly-offline path. Its caller may still hold a cloud token
+    // (the hook resolves the DEFAULT env, not the one the command used), so the token check below
+    // is not enough on its own.
+    if (command === 'local' || command.startsWith('local '))
+        return;
+    if (!env.authToken || !env.tenantId)
+        return;
+    // A blackholing proxy hangs rather than rejecting, so a bare await would freeze the CLI after
+    // its real work is done. The timer both aborts the request and wins the race, so we stop
+    // waiting even if the transport ignores the signal.
+    const controller = new AbortController();
+    let giveUp = () => { };
+    const abandoned = new Promise((resolve) => {
+        giveUp = resolve;
+    });
+    const timer = setTimeout(() => {
+        controller.abort();
+        giveUp();
+    }, TELEMETRY_TIMEOUT_MS);
+    try {
+        await Promise.race([
+            fetch(`${env.gatewayUrl}/telemetry/ingest`, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${env.authToken}`,
+                    'x-tenant-id': env.tenantId,
+                },
+                body: JSON.stringify({
+                    eventName: 'cli.command',
+                    category: 'engagement',
+                    platform: 'cli',
+                    properties: { command },
+                }),
+            }),
+            abandoned,
+        ]);
+    }
+    catch {
+        // Telemetry must never fail a command. Swallowing here is driven by a test, not defensive
+        // habit - see "resolves when the gateway rejects" in usage-telemetry.test.ts.
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=usage-telemetry.js.map

package/dist/lib/usage-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-telemetry.js","sourceRoot":"","sources":["../../src/lib/usage-telemetry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAE1C,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAsB,EAAE,OAAe;IAC9E,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,KAAK,GAAG;QAAE,OAAO;IACnD,4FAA4F;IAC5F,8FAA8F;IAC9F,4BAA4B;IAC5B,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO;IAChE,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO;IAE5C,8FAA8F;IAC9F,yFAAyF;IACzF,oDAAoD;IACpD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,IAAI,MAAM,GAAe,GAAG,EAAE,GAAE,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC9C,MAAM,GAAG,OAAO,CAAC;IACnB,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,EAAE,CAAC;IACX,CAAC,EAAE,oBAAoB,CAAC,CAAC;IAEzB,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,IAAI,CAAC;YACjB,KAAK,CAAC,GAAG,GAAG,CAAC,UAAU,mBAAmB,EAAE;gBAC1C,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,UAAU,CAAC,MAAM;gBACzB,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,aAAa,EAAE,UAAU,GAAG,CAAC,SAAS,EAAE;oBACxC,aAAa,EAAE,GAAG,CAAC,QAAQ;iBAC5B;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,SAAS,EAAE,aAAa;oBACxB,QAAQ,EAAE,YAAY;oBACtB,QAAQ,EAAE,KAAK;oBACf,UAAU,EAAE,EAAE,OAAO,EAAE;iBACxB,CAAC;aACH,CAAC;YACF,SAAS;SACV,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,0FAA0F;QAC1F,8EAA8E;IAChF,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/lib/value-rollup.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ALI-215: the "what your graph did for you" value rollup. Aggregates the gateway's
+ * per-tenant value signals into one normalized shape the status readout renders. Each
+ * source is fetched independently and a failure nulls only its own field - an old gateway
+ * missing /decisions/reuse-rate must not blank the whole readout.
+ */
+export interface ValueRollup {
+    decisions: number;
+    conflictsCaught: number;
+    duplicates: number;
+    supersessions: number;
+    reuseRate: number | null;
+    healthGrade: string | null;
+}
+export interface ValueRollupClient {
+    getStats(): Promise<{
+        snapshots?: number;
+    }>;
+    getConflictImpact(): Promise<{
+        total?: number;
+    }>;
+    getLinkCounts(): Promise<{
+        duplicates_count?: number;
+        supersessions_count?: number;
+    }>;
+    getReuseRate(): Promise<{
+        rate: number | null;
+    }>;
+    getHealth(): Promise<{
+        compositeScore?: {
+            grade?: string;
+        };
+    }>;
+}
+export declare function fetchValueRollup(client: ValueRollupClient): Promise<ValueRollup>;
+/**
+ * Render the value rollup as a terminal readout. Pure string builder (no I/O) so it's
+ * unit-testable. Names value units - conflicts caught / duplicates / superseded / reuse -
+ * never "connections". The upgrade nudge is EARNED: only shown when the graph has produced
+ * real value (a conflict, duplicate, or supersession), tying the nudge to the sharing
+ * ceiling rather than a generic wall.
+ */
+export declare function renderValueReadout(r: ValueRollup, opts: {
+    mode: 'cloud' | 'local';
+}): string;
+export interface LocalRollupDb {
+    getStats(): {
+        decisions: number;
+    };
+    listLinks(filter?: {
+        relation?: string;
+    }): unknown[];
+}
+/**
+ * The offline honest subset: decisions + conflict/duplicate/supersession counts derivable
+ * from the local decision_links table. Reuse rate and composite health need the gateway,
+ * so they are null here - we do NOT fabricate them offline (ALI-215 decision).
+ */
+export declare function localValueRollup(db: LocalRollupDb): ValueRollup;
+//# sourceMappingURL=value-rollup.d.ts.map

package/dist/lib/value-rollup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-rollup.d.ts","sourceRoot":"","sources":["../../src/lib/value-rollup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,IAAI,OAAO,CAAC;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5C,iBAAiB,IAAI,OAAO,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,aAAa,IAAI,OAAO,CAAC;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtF,YAAY,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACjD,SAAS,IAAI,OAAO,CAAC;QAAE,cAAc,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CAC/D;AAUD,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAiBtF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;CAAE,GAAG,MAAM,CAsB5F;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,IAAI;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC,SAAS,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,EAAE,CAAC;CACtD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,aAAa,GAAG,WAAW,CAU/D"}

package/dist/lib/value-rollup.js

@@ -0,0 +1,78 @@
+/**
+ * ALI-215: the "what your graph did for you" value rollup. Aggregates the gateway's
+ * per-tenant value signals into one normalized shape the status readout renders. Each
+ * source is fetched independently and a failure nulls only its own field - an old gateway
+ * missing /decisions/reuse-rate must not blank the whole readout.
+ */
+async function settle(p) {
+    try {
+        return await p;
+    }
+    catch {
+        return null;
+    }
+}
+export async function fetchValueRollup(client) {
+    const [stats, impact, links, reuse, health] = await Promise.all([
+        settle(client.getStats()),
+        settle(client.getConflictImpact()),
+        settle(client.getLinkCounts()),
+        settle(client.getReuseRate()),
+        settle(client.getHealth()),
+    ]);
+    return {
+        decisions: stats?.snapshots ?? 0,
+        conflictsCaught: impact?.total ?? 0,
+        duplicates: links?.duplicates_count ?? 0,
+        supersessions: links?.supersessions_count ?? 0,
+        reuseRate: reuse ? reuse.rate : null,
+        healthGrade: health?.compositeScore?.grade ?? null,
+    };
+}
+/**
+ * Render the value rollup as a terminal readout. Pure string builder (no I/O) so it's
+ * unit-testable. Names value units - conflicts caught / duplicates / superseded / reuse -
+ * never "connections". The upgrade nudge is EARNED: only shown when the graph has produced
+ * real value (a conflict, duplicate, or supersession), tying the nudge to the sharing
+ * ceiling rather than a generic wall.
+ */
+export function renderValueReadout(r, opts) {
+    const reuse = r.reuseRate === null ? 'n/a' : `${Math.round(r.reuseRate * 100)}%`;
+    const lines = [
+        `  ${r.decisions} decisions in your graph`,
+        `  ${r.conflictsCaught} conflicts caught`,
+        `  ${r.duplicates} duplicates found`,
+        `  ${r.supersessions} decisions superseded`,
+        `  reuse rate: ${reuse}`,
+    ];
+    if (r.healthGrade) {
+        lines.push(`  health: ${r.healthGrade}`);
+    }
+    if (opts.mode === 'local') {
+        lines.push('');
+        lines.push('  Reuse rate and health need the cloud graph - run `align login` to see them.');
+    }
+    const hasValue = r.conflictsCaught > 0 || r.duplicates > 0 || r.supersessions > 0;
+    if (hasValue) {
+        lines.push('');
+        lines.push('  Share this graph with your team: https://app.align.tech/pricing');
+    }
+    return lines.join('\n');
+}
+/**
+ * The offline honest subset: decisions + conflict/duplicate/supersession counts derivable
+ * from the local decision_links table. Reuse rate and composite health need the gateway,
+ * so they are null here - we do NOT fabricate them offline (ALI-215 decision).
+ */
+export function localValueRollup(db) {
+    const count = (relation) => db.listLinks({ relation }).length;
+    return {
+        decisions: db.getStats().decisions,
+        conflictsCaught: count('conflicts_with') + count('contradicts'),
+        duplicates: count('duplicates'),
+        supersessions: count('supersedes'),
+        reuseRate: null,
+        healthGrade: null,
+    };
+}
+//# sourceMappingURL=value-rollup.js.map

package/dist/lib/value-rollup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-rollup.js","sourceRoot":"","sources":["../../src/lib/value-rollup.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligndottech/cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Align CLI - capture decisions, check alignment, and manage connectors",
   "keywords": [
@@ -33,7 +33,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@aligndottech/connector-core": "^0.2.0",
+    "@aligndottech/connector-core": "^0.4.0",
     "@clack/prompts": "^0.9.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.10.0",