@askthew/mcp-plugin 0.2.8 → 0.4.2

package/dist/install.test.js

@@ -0,0 +1,297 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { formatInstallCommand, installBehaviorInstructions, installHostConfig, mergeHostSettings, resolveSettingsPath, sendInstallHeartbeat, uninstallBehaviorInstructions, uninstallHostConfig, verificationNextStep, } from "./install.js";
+test("mergeHostSettings preserves unrelated MCP servers and replaces askthew", () => {
+    const tempProject = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-merge-project-"));
+    fs.writeFileSync(path.join(tempProject, "package.json"), "{}", "utf8");
+    const merged = mergeHostSettings({
+        existingSettings: {
+            theme: "dark",
+            mcpServers: {
+                github: {
+                    command: "github-mcp",
+                },
+                askthew: {
+                    command: "old-command",
+                },
+            },
+        },
+        hostType: "codex",
+        token: "token-123",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+        cwd: tempProject,
+    });
+    assert.deepEqual(merged.theme, "dark");
+    assert.deepEqual(Object.keys(merged.mcpServers ?? {}).sort(), ["askthew_workspace_a", "github"]);
+    assert.deepEqual(merged.mcpServers.askthew_workspace_a, {
+        command: "npx",
+        args: ["-y", "--prefer-online", "@askthew/mcp-plugin@latest"],
+        env: {
+            ASKTHEW_INSTALL_TOKEN: "token-123",
+            ASKTHEW_API_URL: "https://askthew.example.com",
+            ASKTHEW_HOST_TYPE: "codex",
+            ASKTHEW_SERVER_NAME: "askthew_workspace_a",
+            ASKTHEW_REPO_NAME: path.basename(tempProject),
+            ASKTHEW_REPO_ROOT: tempProject,
+        },
+    });
+    fs.rmSync(tempProject, { recursive: true, force: true });
+});
+test("installHostConfig writes Claude Code local MCP settings and stays idempotent", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-mcp-install-"));
+    const tempProject = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-claude-project-"));
+    const settingsPath = resolveSettingsPath({
+        hostType: "claude_code",
+        homeDirectory: tempHome,
+    });
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify({
+        projects: {
+            [tempProject]: {
+                mcpServers: {
+                    github: {
+                        command: "github-mcp",
+                    },
+                },
+            },
+        },
+    }, null, 2), "utf8");
+    const first = installHostConfig({
+        hostType: "claude_code",
+        token: "token-456",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+        clientId: "claude_code",
+        clientLabel: "Claude Code",
+        homeDirectory: tempHome,
+        cwd: tempProject,
+    });
+    const afterFirst = fs.readFileSync(settingsPath, "utf8");
+    const second = installHostConfig({
+        hostType: "claude_code",
+        token: "token-456",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+        clientId: "claude_code",
+        clientLabel: "Claude Code",
+        homeDirectory: tempHome,
+        cwd: tempProject,
+    });
+    const afterSecond = fs.readFileSync(settingsPath, "utf8");
+    const parsed = JSON.parse(afterSecond);
+    const projectServers = parsed.projects[tempProject].mcpServers;
+    assert.equal(first.settingsPath, settingsPath);
+    assert.equal(second.settingsPath, settingsPath);
+    assert.equal(afterFirst, afterSecond);
+    assert.deepEqual(Object.keys(projectServers ?? {}).sort(), ["askthew_workspace_a", "github"]);
+    assert.equal(projectServers.askthew_workspace_a.env.ASKTHEW_INSTALL_TOKEN, "token-456");
+    assert.equal(projectServers.askthew_workspace_a.env.ASKTHEW_CLIENT_ID, "claude_code");
+    assert.equal(projectServers.askthew_workspace_a.env.ASKTHEW_CLIENT_LABEL, "Claude Code");
+    fs.rmSync(tempHome, { recursive: true, force: true });
+    fs.rmSync(tempProject, { recursive: true, force: true });
+});
+test("installHostConfig writes Codex MCP servers to config.toml", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-mcp-multi-workspace-"));
+    const settingsPath = resolveSettingsPath({
+        hostType: "codex",
+        homeDirectory: tempHome,
+    });
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, [
+        'model = "gpt-5"',
+        "",
+        "[mcp_servers.github]",
+        'command = "github-mcp"',
+        "",
+    ].join("\n"), "utf8");
+    installHostConfig({
+        hostType: "codex",
+        token: "token-a",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+        homeDirectory: tempHome,
+    });
+    installHostConfig({
+        hostType: "codex",
+        token: "token-b",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_b",
+        homeDirectory: tempHome,
+    });
+    const toml = fs.readFileSync(settingsPath, "utf8");
+    assert.match(toml, /\[mcp_servers\.github\]/);
+    assert.match(toml, /\[mcp_servers\.askthew_workspace_a\]/);
+    assert.match(toml, /\[mcp_servers\.askthew_workspace_b\]/);
+    assert.match(toml, /ASKTHEW_INSTALL_TOKEN = "token-a"/);
+    assert.match(toml, /ASKTHEW_INSTALL_TOKEN = "token-b"/);
+    fs.rmSync(tempHome, { recursive: true, force: true });
+});
+test("installHostConfig dry run returns merged JSON without writing a file", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-mcp-dry-run-"));
+    const settingsPath = resolveSettingsPath({
+        hostType: "codex",
+        homeDirectory: tempHome,
+    });
+    const result = installHostConfig({
+        hostType: "codex",
+        token: "token-789",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+        homeDirectory: tempHome,
+        dryRun: true,
+    });
+    assert.equal(result.wroteFile, false);
+    assert.equal(fs.existsSync(settingsPath), false);
+    assert.match(result.json, /ASKTHEW_INSTALL_TOKEN/);
+    assert.match(result.json, /\[mcp_servers\.askthew_workspace_a\]/);
+    fs.rmSync(tempHome, { recursive: true, force: true });
+});
+test("installHostConfig writes Cursor global mcp.json", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-cursor-mcp-"));
+    const settingsPath = resolveSettingsPath({
+        hostType: "cursor",
+        homeDirectory: tempHome,
+    });
+    installHostConfig({
+        hostType: "cursor",
+        token: "token-cursor",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew",
+        homeDirectory: tempHome,
+    });
+    const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    assert.deepEqual(Object.keys(parsed.mcpServers ?? {}), ["askthew"]);
+    assert.equal(parsed.mcpServers.askthew.command, "npx");
+    assert.equal(parsed.mcpServers.askthew.env.ASKTHEW_HOST_TYPE, "cursor");
+    fs.rmSync(tempHome, { recursive: true, force: true });
+});
+test("formatInstallCommand emits the one-command guided install form", () => {
+    const command = formatInstallCommand({
+        hostType: "codex",
+        token: "token-abc",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew_workspace_a",
+    });
+    assert.equal(command, 'npx -y --prefer-online @askthew/mcp-plugin@latest install --host codex --token "token-abc" --api-url "https://askthew.example.com" --server-name "askthew_workspace_a"');
+});
+test("verificationNextStep points users to every-session startup capture", () => {
+    const nextStep = verificationNextStep("codex");
+    assert.match(nextStep, /Refresh Ask The W/);
+    assert.match(nextStep, /every new Codex session in this repo/);
+    assert.match(nextStep, /before plan mode or exploration/);
+    assert.match(nextStep, /list_mcp_resources\/list_mcp_resource_templates may be empty/);
+});
+test("sendInstallHeartbeat pings Ask The W after config install", async () => {
+    const calls = [];
+    const ok = await sendInstallHeartbeat({
+        hostType: "codex",
+        token: "token-abc",
+        apiUrl: "https://askthew.example.com/",
+        serverName: "askthew",
+        cwd: process.cwd(),
+        fetchImpl: async (url, init) => {
+            calls.push({
+                url: String(url),
+                body: JSON.parse(String(init?.body ?? "{}")),
+            });
+            return new Response("{}", { status: 200 });
+        },
+    });
+    assert.equal(ok, true);
+    assert.equal(calls[0]?.url, "https://askthew.example.com/api/connectors/mcp/heartbeat");
+    assert.equal(calls[0]?.body.installToken, "token-abc");
+    assert.equal(calls[0]?.body.hostType, "codex");
+    assert.equal(calls[0]?.body.serverName, "askthew");
+    assert.equal(calls[0]?.body.clientId, "codex");
+});
+test("installBehaviorInstructions adds persistent Codex tracking rules without clobbering existing instructions", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-agent-instructions-"));
+    const claudePath = path.join(tempRoot, "CLAUDE.md");
+    const agentsPath = path.join(tempRoot, "AGENTS.md");
+    fs.writeFileSync(agentsPath, "# Existing instructions\n\nKeep this section.\n", "utf8");
+    const result = installBehaviorInstructions({
+        hostType: "codex",
+        cwd: tempRoot,
+    });
+    const claudeContents = fs.readFileSync(claudePath, "utf8");
+    const contents = fs.readFileSync(agentsPath, "utf8");
+    assert.equal(result.path, agentsPath);
+    assert.deepEqual(result.paths, [claudePath, agentsPath]);
+    assert.match(claudeContents, /Ask The W Plugin/);
+    assert.match(claudeContents, /At the start of every new Codex session in this repo/);
+    assert.match(contents, /# Existing instructions/);
+    assert.match(contents, /Ask The W Plugin/);
+    assert.match(contents, /capture_session_signal/);
+    assert.match(contents, /At the start of every new Codex session in this repo/);
+    assert.match(contents, /before plan mode, exploration, or any normal reply/);
+    assert.match(contents, /metadata\.recovered_missed_startup=true/);
+    assert.match(contents, /before using tools that write files/);
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+test("installBehaviorInstructions creates Cursor rule file", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-cursor-rules-"));
+    const result = installBehaviorInstructions({
+        hostType: "cursor",
+        cwd: tempRoot,
+    });
+    assert.equal(result.path, path.join(tempRoot, ".cursor", "rules", "askthew.mdc"));
+    assert.match(fs.readFileSync(result.path, "utf8"), /alwaysApply: true/);
+    assert.match(fs.readFileSync(result.path, "utf8"), /Ask The W Plugin/);
+    assert.match(fs.readFileSync(result.path, "utf8"), /At the start of every new Cursor session/);
+    assert.match(fs.readFileSync(result.path, "utf8"), /before plan mode, exploration, or any normal reply/);
+    assert.match(fs.readFileSync(result.path, "utf8"), /metadata\.recovered_missed_startup=true/);
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+test("installBehaviorInstructions adds stack-specific verification nudges", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-stack-rules-"));
+    fs.writeFileSync(path.join(tempRoot, "package.json"), JSON.stringify({
+        dependencies: {
+            next: "^15.0.0",
+            openai: "^5.0.0",
+            vite: "^6.0.0",
+        },
+    }), "utf8");
+    const result = installBehaviorInstructions({
+        hostType: "codex",
+        cwd: tempRoot,
+        dryRun: true,
+    });
+    assert.match(result.content, /Next\.js detected/);
+    assert.match(result.content, /OpenAI SDK detected/);
+    assert.match(result.content, /Vite detected/);
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+test("uninstall removes host config and Ask The W agent instruction blocks", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-uninstall-home-"));
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "askthew-uninstall-project-"));
+    installHostConfig({
+        hostType: "codex",
+        token: "token-uninstall",
+        apiUrl: "https://askthew.example.com",
+        serverName: "askthew",
+        homeDirectory: tempHome,
+    });
+    installBehaviorInstructions({
+        hostType: "codex",
+        cwd: tempRoot,
+    });
+    const removed = uninstallHostConfig({
+        hostType: "codex",
+        serverName: "askthew",
+        homeDirectory: tempHome,
+    });
+    const instructions = uninstallBehaviorInstructions({
+        hostType: "codex",
+        cwd: tempRoot,
+    });
+    assert.doesNotMatch(fs.readFileSync(removed.settingsPath, "utf8"), /askthew/);
+    assert.equal(instructions.paths.length, 2);
+    assert.doesNotMatch(fs.readFileSync(path.join(tempRoot, "AGENTS.md"), "utf8"), /ASKTHEW_PLUGIN_INSTRUCTIONS_START/);
+    assert.doesNotMatch(fs.readFileSync(path.join(tempRoot, "CLAUDE.md"), "utf8"), /ASKTHEW_PLUGIN_INSTRUCTIONS_START/);
+    fs.rmSync(tempHome, { recursive: true, force: true });
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+});

package/dist/lib/auth-magic-link.d.ts

@@ -0,0 +1,22 @@
+import type { CliCredentials } from "./free-tier-policy.js";
+export interface MagicLinkClientOptions {
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function requestMagicLinkCode(input: {
+    email: string;
+    deviceLabel?: string;
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    requestId: string;
+    expiresAt: string;
+    devCode?: string;
+}>;
+export declare function verifyMagicLinkCode(input: {
+    requestId: string;
+    code: string;
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+    telemetryOptOut?: boolean;
+}): Promise<CliCredentials>;

package/dist/lib/auth-magic-link.js

@@ -0,0 +1,43 @@
+import { credentialsPath, writePrivateJson } from "./paths.js";
+function baseUrl(apiUrl) {
+    return (apiUrl?.trim() || process.env.ASKTHEW_API_URL?.trim() || "https://app.askthew.com").replace(/\/$/, "");
+}
+async function requestJson(route, body, options) {
+    const fetcher = options.fetchImpl ?? fetch;
+    const response = await fetcher(`${baseUrl(options.apiUrl)}${route}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+        const message = payload && typeof payload === "object" && "error" in payload
+            ? String(payload.error)
+            : "Ask The W auth request failed.";
+        throw new Error(message);
+    }
+    return payload;
+}
+export async function requestMagicLinkCode(input) {
+    return requestJson("/api/cli/v1/magic-link/request", {
+        email: input.email,
+        deviceLabel: input.deviceLabel,
+    }, input);
+}
+export async function verifyMagicLinkCode(input) {
+    const verified = await requestJson("/api/cli/v1/magic-link/verify", {
+        requestId: input.requestId,
+        code: input.code,
+    }, input);
+    const credentials = {
+        email: verified.email,
+        userId: verified.userId,
+        cliToken: verified.cliToken,
+        cliTokenId: verified.cliTokenId,
+        accountStatus: verified.accountStatus,
+        apiUrl: input.apiUrl,
+        telemetryOptOut: input.telemetryOptOut,
+    };
+    writePrivateJson(credentialsPath(), credentials);
+    return credentials;
+}

package/dist/lib/auth-pending.d.ts

@@ -0,0 +1,23 @@
+type CliConfig = {
+    pendingAuth?: {
+        email: string;
+        requestId: string;
+        expiresAt: string;
+        telemetryOptOut?: boolean;
+    };
+};
+export declare function savePendingAuth(input: NonNullable<CliConfig["pendingAuth"]>, env?: NodeJS.ProcessEnv): void;
+export declare function clearPendingAuth(env?: NodeJS.ProcessEnv): void;
+export declare function pendingAuthForEmail(email: string, env?: NodeJS.ProcessEnv): {
+    email: string;
+    requestId: string;
+    expiresAt: string;
+    telemetryOptOut?: boolean;
+} | null;
+export declare function pendingAuth(env?: NodeJS.ProcessEnv): {
+    email: string;
+    requestId: string;
+    expiresAt: string;
+    telemetryOptOut?: boolean;
+} | null;
+export {};

package/dist/lib/auth-pending.js

@@ -0,0 +1,36 @@
+import { configPath, readJsonFile, writePrivateJson } from "./paths.js";
+function loadCliConfig(env = process.env) {
+    return readJsonFile(configPath(env)) ?? {};
+}
+export function savePendingAuth(input, env = process.env) {
+    const config = loadCliConfig(env);
+    writePrivateJson(configPath(env), {
+        ...config,
+        pendingAuth: input,
+    });
+}
+export function clearPendingAuth(env = process.env) {
+    const config = loadCliConfig(env);
+    if (!config.pendingAuth)
+        return;
+    const { pendingAuth: _pendingAuth, ...next } = config;
+    writePrivateJson(configPath(env), next);
+}
+export function pendingAuthForEmail(email, env = process.env) {
+    const pending = pendingAuth(env);
+    if (!pending || pending.email.toLowerCase() !== email.toLowerCase()) {
+        return null;
+    }
+    return pending;
+}
+export function pendingAuth(env = process.env) {
+    const pending = loadCliConfig(env).pendingAuth;
+    if (!pending) {
+        return null;
+    }
+    if (Number.isFinite(Date.parse(pending.expiresAt)) && Date.parse(pending.expiresAt) <= Date.now()) {
+        clearPendingAuth(env);
+        return null;
+    }
+    return pending;
+}

package/dist/lib/cli-actions.d.ts

@@ -0,0 +1,28 @@
+import type { LocalStore } from "./local-store.js";
+export declare function localScopeKey(cwd?: string): string;
+export declare function installPreCommitHook(input?: {
+    cwd?: string;
+}): string;
+export declare function stagedFiles(input?: {
+    cwd?: string;
+}): string[];
+export declare function preCommitDecisionGap(input: {
+    store: LocalStore;
+    stagedFiles: string[];
+    now?: Date;
+    scopeKey?: string | null;
+}): {
+    missing: boolean;
+    matchedSignals: number[];
+};
+export declare function isoWeek(date: Date): string;
+export declare function buildWeeklyDigest(input: {
+    store: LocalStore;
+    now?: Date;
+    scopeKey?: string | null;
+}): string;
+export declare function writeWeeklyDigest(input: {
+    store: LocalStore;
+    now?: Date;
+    outputDir?: string;
+}): string;

package/dist/lib/cli-actions.js

@@ -0,0 +1,104 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { configPath, readJsonFile } from "./paths.js";
+import { resolvePluginScope } from "../scope.js";
+function readConfig() {
+    return readJsonFile(configPath()) ?? {};
+}
+export function localScopeKey(cwd = process.cwd()) {
+    const scope = resolvePluginScope(cwd);
+    return [scope.repoRoot || scope.repoName || cwd, scope.appPath ?? "", scope.serviceName ?? ""]
+        .filter(Boolean)
+        .join("::")
+        .replace(/\s+/g, " ")
+        .slice(0, 500);
+}
+export function installPreCommitHook(input = {}) {
+    const cwd = path.resolve(input.cwd ?? process.cwd());
+    const gitDir = execFileSync("git", ["rev-parse", "--git-dir"], { cwd, encoding: "utf8" }).trim();
+    const hookPath = path.resolve(cwd, gitDir, "hooks", "pre-commit");
+    const hook = [
+        "#!/bin/sh",
+        "# Ask The W pre-commit decision prompt",
+        "npx -y --prefer-online @askthew/mcp-plugin@latest hook-check --pre-commit",
+        "",
+    ].join("\n");
+    fs.mkdirSync(path.dirname(hookPath), { recursive: true });
+    fs.writeFileSync(hookPath, hook, { encoding: "utf8", mode: 0o755 });
+    fs.chmodSync(hookPath, 0o755);
+    return hookPath;
+}
+export function stagedFiles(input = {}) {
+    const cwd = path.resolve(input.cwd ?? process.cwd());
+    return execFileSync("git", ["diff", "--cached", "--name-only"], { cwd, encoding: "utf8" })
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+export function preCommitDecisionGap(input) {
+    const staged = new Set(input.stagedFiles);
+    if (staged.size === 0) {
+        return { missing: false, matchedSignals: [] };
+    }
+    const nowMs = (input.now ?? new Date()).getTime();
+    const scopeKey = input.scopeKey;
+    const recentImplementationSignals = input.store
+        .listSignals({ scopeKey, limit: 100000 })
+        .filter((signal) => signal.kind === "implementation_update")
+        .filter((signal) => nowMs - new Date(signal.capturedAt).getTime() <= 14 * 24 * 60 * 60 * 1000)
+        .filter((signal) => signal.filesTouched.some((file) => staged.has(file)));
+    if (recentImplementationSignals.length === 0) {
+        return { missing: false, matchedSignals: [] };
+    }
+    const matchedSignalIds = new Set(recentImplementationSignals.map((signal) => signal.id));
+    const linkedDecision = input.store.listDecisions({ scopeKey, limit: 100000 }).some((decision) => {
+        if (decision.sourceSignalIds.some((id) => matchedSignalIds.has(id)))
+            return true;
+        return decision.files.some((file) => staged.has(file));
+    });
+    return {
+        missing: !linkedDecision,
+        matchedSignals: Array.from(matchedSignalIds),
+    };
+}
+export function isoWeek(date) {
+    const utcDate = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+    const day = utcDate.getUTCDay() || 7;
+    utcDate.setUTCDate(utcDate.getUTCDate() + 4 - day);
+    const yearStart = new Date(Date.UTC(utcDate.getUTCFullYear(), 0, 1));
+    const week = Math.ceil(((utcDate.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+    return `${utcDate.getUTCFullYear()}-${String(week).padStart(2, "0")}`;
+}
+export function buildWeeklyDigest(input) {
+    const now = input.now ?? new Date();
+    const since = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const scopeKey = input.scopeKey;
+    const decisions = input.store.listDecisions({ scopeKey, since, limit: 100000 });
+    const signals = input.store.listSignals({ scopeKey, limit: 100000 }).filter((signal) => signal.capturedAt >= since);
+    const lines = [
+        `# Ask The W Weekly Decision Digest ${isoWeek(now)}`,
+        "",
+        `Signals captured: ${signals.length}`,
+        `Decisions captured: ${decisions.length}`,
+        "",
+        "## Decisions",
+        ...(decisions.length
+            ? decisions.map((decision) => `- ${decision.headline} (${decision.status})${decision.why ? ` - ${decision.why}` : ""}`)
+            : ["- No decisions captured this week."]),
+    ];
+    if (readConfig().digest?.footer !== false) {
+        lines.push("", "_Captured by Ask The W._");
+    }
+    return lines.join("\n");
+}
+export function writeWeeklyDigest(input) {
+    const now = input.now ?? new Date();
+    const configuredOutputDir = input.outputDir ?? process.env.ASKTHEW_DIGEST_DIR?.trim();
+    const outputDir = configuredOutputDir || path.join(os.homedir(), "Documents");
+    fs.mkdirSync(outputDir, { recursive: true });
+    const filePath = path.join(outputDir, `askthew-digest-${isoWeek(now)}.md`);
+    fs.writeFileSync(filePath, `${buildWeeklyDigest({ store: input.store, now, scopeKey: localScopeKey() })}\n`, "utf8");
+    return filePath;
+}

package/dist/lib/free-install-registration.d.ts

@@ -0,0 +1,27 @@
+import { type LocalInstallIdentity, type PublicInstallIdentity } from "./local-identity.js";
+export interface FreeInstallRegistrationOptions {
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function registerFreeInstall(input: {
+    identity: LocalInstallIdentity;
+    deviceLabel?: string;
+    repo?: Record<string, unknown>;
+    options?: FreeInstallRegistrationOptions;
+}): Promise<{
+    ok: boolean;
+    registeredAt: string;
+}>;
+export declare function tryRegisterFreeInstall(input: {
+    identity: LocalInstallIdentity;
+    deviceLabel?: string;
+    repo?: Record<string, unknown>;
+    options?: FreeInstallRegistrationOptions;
+}): Promise<{
+    ok: boolean;
+    registeredAt: string;
+} | {
+    ok: boolean;
+    error: string;
+}>;
+export declare function describeFreeIdentity(identity: PublicInstallIdentity): string;

package/dist/lib/free-install-registration.js

@@ -0,0 +1,52 @@
+import crypto from "node:crypto";
+import { markLocalIdentityRegistered, } from "./local-identity.js";
+function baseUrl(apiUrl) {
+    return (apiUrl?.trim() || process.env.ASKTHEW_API_URL?.trim() || "https://app.askthew.com").replace(/\/$/, "");
+}
+function hashClaimCode(code) {
+    return crypto.createHash("sha256").update(code.trim()).digest("hex");
+}
+function safeMessage(error) {
+    return error instanceof Error ? error.message : "Registration failed.";
+}
+export async function registerFreeInstall(input) {
+    const fetcher = input.options?.fetchImpl ?? fetch;
+    const response = await fetcher(`${baseUrl(input.options?.apiUrl ?? input.identity.apiUrl)}/api/cli/v1/free-installs/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            installId: input.identity.installId,
+            publicKey: input.identity.publicKey,
+            claimCodeHash: hashClaimCode(input.identity.claimCode),
+            emailClaim: input.identity.emailClaim,
+            deviceLabel: input.deviceLabel,
+            repo: input.repo ?? {},
+        }),
+    });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+        throw new Error(payload?.error ? String(payload.error) : "Free install registration failed.");
+    }
+    const registeredAt = payload && typeof payload === "object" && typeof payload.registeredAt === "string"
+        ? payload.registeredAt
+        : new Date().toISOString();
+    markLocalIdentityRegistered({ registeredAt });
+    return { ok: true, registeredAt };
+}
+export async function tryRegisterFreeInstall(input) {
+    try {
+        return await registerFreeInstall(input);
+    }
+    catch (error) {
+        markLocalIdentityRegistered({ registrationError: safeMessage(error) });
+        return { ok: false, error: safeMessage(error) };
+    }
+}
+export function describeFreeIdentity(identity) {
+    return [
+        `Install ID: ${identity.installId}`,
+        identity.emailClaim ? `Email claim: ${identity.emailClaim} (unverified)` : "Email claim: none",
+        `Claim code: ${identity.claimCode}`,
+        identity.registeredAt ? `Registered: ${identity.registeredAt}` : "Registered: pending",
+    ].join("\n");
+}

package/dist/lib/free-tier-policy.d.ts

@@ -0,0 +1,23 @@
+import { type LocalInstallIdentity } from "./local-identity.js";
+export type McpMode = "paid" | "free" | "free_pending_auth" | "unauthenticated";
+export interface CliCredentials {
+    email?: string;
+    userId: string;
+    cliToken: string;
+    cliTokenId: string;
+    apiUrl?: string;
+    telemetryOptOut?: boolean;
+    accountStatus?: "new_dormant" | "existing_active";
+    identityKind?: "legacy_token" | "local_install";
+    installId?: string;
+    localIdentity?: LocalInstallIdentity;
+}
+export interface ModeResolution {
+    mode: McpMode;
+    installToken?: string;
+    cliCredentials?: CliCredentials;
+    reason: string;
+}
+export declare function loadCliCredentials(env?: NodeJS.ProcessEnv): CliCredentials | null;
+export declare function resolveMcpMode(env?: NodeJS.ProcessEnv): ModeResolution;
+export declare function isTelemetryOptedOut(env?: NodeJS.ProcessEnv, credentials?: CliCredentials | null): boolean;