@blastin-dev/clocktopus-cli 0.1.4 → 0.2.0

package/dist/src/lib/repo-guidance.js

@@ -0,0 +1,123 @@
+import { ApiError, get } from "./api.js";
+import { getApiUrl } from "./config.js";
+import { formatAgo } from "./format.js";
+import { getRepositoryRemote } from "./git.js";
+import { RepoStatusSchema } from "./validators.js";
+/**
+ * Fetches readiness for the repository the CLI is standing in.
+ *
+ * Returns null when there is nothing to ask about — outside a git tree, or
+ * when the server is unreachable. A failure here must never fail `setup`:
+ * the local configuration it just wrote is valid regardless.
+ */
+export async function fetchRepoStatus(cwd = process.cwd()) {
+    const remote = getRepositoryRemote(cwd);
+    if (!remote)
+        return null;
+    try {
+        const data = await get(`/api/agent/repo-status?repositoryUrl=${encodeURIComponent(remote)}`);
+        return RepoStatusSchema.parse(data);
+    }
+    catch (error) {
+        if (error instanceof ApiError)
+            return null;
+        return null;
+    }
+}
+export function attributionCheck(status) {
+    const { attribution, repository } = status;
+    const where = repository?.displayUrl ?? "this repository";
+    switch (attribution.reason) {
+        case "attributed":
+            return {
+                label: "Project",
+                ok: true,
+                detail: attribution.projectNames[0] ?? "attached",
+            };
+        case "no_matching_project":
+            return {
+                label: "Project",
+                ok: false,
+                detail: `${where} is not attached to any project`,
+                fix: "Attach it under Projects → (your project) → Repositories.\n" +
+                    "      Until then this repo's agent spend is recorded, but lands in\n" +
+                    "      the unattributed row instead of against a client.",
+            };
+        case "ambiguous_project":
+            return {
+                label: "Project",
+                ok: false,
+                // Refusing to guess is the designed behaviour, not a bug — billing
+                // one client for another's work is worse than billing nobody.
+                detail: `${where} is attached to ${attribution.projectNames.length} projects (${attribution.projectNames.join(", ")})`,
+                fix: "Clocktopus will not guess which client to bill, so these sessions\n" +
+                    "      stay unattributed. Remove the repository from all but one project.",
+            };
+        case "unsupported_remote":
+            return {
+                label: "Project",
+                ok: "warn",
+                detail: "remote is not GitHub or Bitbucket",
+                fix: "Spend from this repository is recorded but cannot be attributed —\n" +
+                    "      only GitHub and Bitbucket remotes resolve to a project.",
+            };
+        case "no_repository":
+            return {
+                label: "Project",
+                ok: "warn",
+                detail: "not a git repository",
+                fix: "Run 'clocktopus agent setup' inside a project checkout to check attribution.",
+            };
+    }
+}
+export function commitLaneCheck(status) {
+    const dashboard = getApiUrl().replace(/\/$/, "");
+    switch (status.commitLane.status) {
+        case "delivering":
+            return {
+                label: "Commit lane",
+                ok: true,
+                detail: `last commit received ${formatAgo(status.commitLane.lastCommitAt)}`,
+            };
+        case "no_secret":
+            return {
+                label: "Commit lane",
+                ok: false,
+                detail: "no webhook secret — no commits are reaching Clocktopus",
+                fix: `Create one at ${dashboard}/settings/webhooks, then add a push\n` +
+                    `      webhook to this repository. Guide:\n` +
+                    `      ${dashboard}/docs/guides/setup-github-webhook`,
+            };
+        case "no_delivery":
+            return {
+                label: "Commit lane",
+                ok: false,
+                detail: "no commit has ever arrived from this repository",
+                fix: "Agent spend will be recorded here, but with no human time beside it\n" +
+                    "      the true-cost comparison has only one side. Add a push webhook:\n" +
+                    `        URL     ${status.webhookUrl}\n` +
+                    "        Events  push\n" +
+                    `        Secret  ${dashboard}/settings/webhooks\n` +
+                    "      The URL is per person, not per repository — on a shared repo\n" +
+                    "      each teammate adds their own.",
+            };
+    }
+}
+export function repoChecks(status) {
+    return [attributionCheck(status), commitLaneCheck(status)];
+}
+/** The block `agent setup` prints after writing the local configuration. */
+export function renderRepoBlock(status) {
+    const lines = [];
+    const heading = status.repository?.displayUrl ?? "this directory";
+    lines.push("");
+    lines.push(`Repository  ${heading}`);
+    lines.push("");
+    for (const check of repoChecks(status)) {
+        const symbol = check.ok === true ? "✓" : check.ok === "warn" ? "⚠" : "✗";
+        lines.push(`  ${symbol} ${check.label.padEnd(12)}${check.detail}`);
+        if (check.ok !== true && check.fix)
+            lines.push(`      ${check.fix}`);
+    }
+    return lines;
+}

package/dist/src/lib/validators.d.ts

@@ -36,4 +36,73 @@ export declare const TokenErrorResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type TokenResponse = z.infer<typeof TokenResponseSchema>;
 export type TokenErrorResponse = z.infer<typeof TokenErrorResponseSchema>;
+export declare const IngestTokenSchema: z.ZodObject<{
+    tokenId: z.ZodString;
+    token: z.ZodString;
+    tokenPrefix: z.ZodString;
+    endpoint: z.ZodString;
+}, z.core.$strip>;
+export declare const AgentEndpointSchema: z.ZodObject<{
+    endpoint: z.ZodString;
+}, z.core.$strip>;
+export declare const AgentStatusSchema: z.ZodObject<{
+    endpoint: z.ZodString;
+    window: z.ZodObject<{
+        since: z.ZodString;
+        sessions: z.ZodNumber;
+        unattributedSessions: z.ZodNumber;
+        costMicroUsd: z.ZodNumber;
+    }, z.core.$strip>;
+    hookLane: z.ZodObject<{
+        lastSessionStartedAt: z.ZodNullable<z.ZodString>;
+        repositoryUrl: z.ZodNullable<z.ZodString>;
+        gitBranch: z.ZodNullable<z.ZodString>;
+        cwd: z.ZodNullable<z.ZodString>;
+        attributed: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strip>;
+    metricsLane: z.ZodObject<{
+        lastExportReceivedAt: z.ZodNullable<z.ZodString>;
+        lastModel: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    tokens: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        tokenPrefix: z.ZodString;
+        lastUsedAt: z.ZodNullable<z.ZodString>;
+        usageCount: z.ZodNumber;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const RepoStatusSchema: z.ZodObject<{
+    repository: z.ZodNullable<z.ZodObject<{
+        provider: z.ZodString;
+        ownerRepo: z.ZodString;
+        displayUrl: z.ZodString;
+    }, z.core.$strip>>;
+    attribution: z.ZodObject<{
+        reason: z.ZodEnum<{
+            attributed: "attributed";
+            no_repository: "no_repository";
+            unsupported_remote: "unsupported_remote";
+            no_matching_project: "no_matching_project";
+            ambiguous_project: "ambiguous_project";
+        }>;
+        projectId: z.ZodNullable<z.ZodString>;
+        projectNames: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    commitLane: z.ZodObject<{
+        status: z.ZodEnum<{
+            delivering: "delivering";
+            no_secret: "no_secret";
+            no_delivery: "no_delivery";
+        }>;
+        lastCommitAt: z.ZodNullable<z.ZodString>;
+        hasWebhookSecret: z.ZodBoolean;
+    }, z.core.$strip>;
+    ready: z.ZodBoolean;
+    webhookUrl: z.ZodString;
+}, z.core.$strip>;
+export type IngestTokenResponse = z.infer<typeof IngestTokenSchema>;
+export type AgentStatusResponse = z.infer<typeof AgentStatusSchema>;
+export type RepoStatusResponse = z.infer<typeof RepoStatusSchema>;
 //# sourceMappingURL=validators.d.ts.map

package/dist/src/lib/validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/lib/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,UAAU;;;;;;;;;iBASrB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,eAAO,MAAM,wBAAwB;;;;;;;iBAOnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;iBASnC,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/lib/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,UAAU;;;;;;;;;iBASrB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,eAAO,MAAM,wBAAwB;;;;;;;iBAOnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;iBASnC,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAO1E,eAAO,MAAM,iBAAiB;;;;;iBAM5B,CAAC;AAEH,eAAO,MAAM,mBAAmB;;iBAE9B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6B5B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0B3B,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AACpE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AACpE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/src/lib/validators.js

@@ -32,3 +32,72 @@ export const TokenErrorResponseSchema = z.object({
     ]),
     error_description: z.string().optional(),
 });
+// Agent telemetry (`clocktopus agent …`). The endpoint is always supplied by
+// the server rather than known to the CLI: the receiver lives on its own
+// Router whose URL differs per stage, so a baked-in default would be wrong
+// everywhere but production.
+export const IngestTokenSchema = z.object({
+    tokenId: z.string(),
+    /** Plaintext, returned exactly once — the server stores only a hash. */
+    token: z.string(),
+    tokenPrefix: z.string(),
+    endpoint: z.string(),
+});
+export const AgentEndpointSchema = z.object({
+    endpoint: z.string(),
+});
+export const AgentStatusSchema = z.object({
+    endpoint: z.string(),
+    window: z.object({
+        since: z.string(),
+        sessions: z.number(),
+        unattributedSessions: z.number(),
+        costMicroUsd: z.number(),
+    }),
+    hookLane: z.object({
+        lastSessionStartedAt: z.string().nullable(),
+        repositoryUrl: z.string().nullable(),
+        gitBranch: z.string().nullable(),
+        cwd: z.string().nullable(),
+        attributed: z.boolean().nullable(),
+    }),
+    metricsLane: z.object({
+        lastExportReceivedAt: z.string().nullable(),
+        lastModel: z.string().nullable(),
+    }),
+    tokens: z.array(z.object({
+        id: z.string(),
+        name: z.string().nullable(),
+        tokenPrefix: z.string(),
+        lastUsedAt: z.string().nullable(),
+        usageCount: z.number(),
+        createdAt: z.string(),
+    })),
+});
+export const RepoStatusSchema = z.object({
+    repository: z
+        .object({
+        provider: z.string(),
+        ownerRepo: z.string(),
+        displayUrl: z.string(),
+    })
+        .nullable(),
+    attribution: z.object({
+        reason: z.enum([
+            "attributed",
+            "no_repository",
+            "unsupported_remote",
+            "no_matching_project",
+            "ambiguous_project",
+        ]),
+        projectId: z.string().nullable(),
+        projectNames: z.array(z.string()),
+    }),
+    commitLane: z.object({
+        status: z.enum(["delivering", "no_secret", "no_delivery"]),
+        lastCommitAt: z.string().nullable(),
+        hasWebhookSecret: z.boolean(),
+    }),
+    ready: z.boolean(),
+    webhookUrl: z.string(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blastin-dev/clocktopus-cli",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "clocktopus": "./dist/bin/clocktopus.js"
@@ -12,13 +12,14 @@
     "commander": "^13.0.0",
     "conf": "^13.0.0",
     "date-fns": "4.1.0",
-    "zod": "4.1.12"
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "22.15.3",
     "eslint": "9.37.0",
     "eslint-plugin-import-x": "^4.16.1",
     "typescript": "5.9.2",
+    "vitest": "^4.1.5",
     "@repo/eslint-config": "0.0.0",
     "@repo/prettier-config": "0.1.0",
     "@repo/typescript-config": "0.0.0"
@@ -28,8 +29,9 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "check-types": "tsc --noEmit",
+    "test": "vitest run",
     "lint": "eslint",
-    "format": "prettier --check . --ignore-path ../../.gitignore",
-    "format:fix": "prettier --write . --ignore-path ../../.gitignore"
+    "format": "prettier --check . --ignore-path ../../.gitignore --ignore-path ../../.prettierignore",
+    "format:fix": "prettier --write . --ignore-path ../../.gitignore --ignore-path ../../.prettierignore"
   }
 }