@mkterswingman/5mghost-twinkler 0.1.4 → 0.1.6

package/README.md

@@ -5,6 +5,7 @@ Lightweight AI runtime for the hosted Twinkler API.
 ```bash
 npm install -g @mkterswingman/5mghost-twinkler
 twinkler ensure --auto-update --json
+twinkler login
 twinkler call GET /api/v1/channel/ibai/summary --query days=30
 ```
 
@@ -13,6 +14,12 @@ clients. `twinkler setup` remains an advanced repair command when a skill target
 was unavailable during install; normal AI workflows should start with
 `twinkler ensure --auto-update --json`.
 
-Auth uses the shared mkterswingman PAT. Do not commit `.env`, `auth.json`,
-PATs, bearer tokens, or any generated secret file to a remote repository. Enter
-PATs through `twinkler login`; do not paste PATs into AI chat.
+Auth defaults to browser OAuth via `twinkler login`. PAT login is an advanced
+fallback with `twinkler login --pat-stdin`.
+
+Watch jobs are remembered locally in `~/.mkterswingman/twinkler/jobs.json` so AI
+sessions can recover active and recent jobs without making users remember job
+IDs.
+
+Do not commit `.env`, `auth.json`, PATs, bearer tokens, or any generated secret
+file to a remote repository.

package/dist/auth.d.ts

@@ -21,6 +21,8 @@ export interface TokenProviderOptions {
     env?: NodeJS.ProcessEnv;
     fetchImpl?: typeof fetch;
     authUrl?: string;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
 }
 export declare function getAuthStatus(options: TokenProviderOptions): AuthStatus;
 export declare function getValidToken(options: TokenProviderOptions): Promise<string | null>;

package/dist/auth.js

@@ -1,9 +1,12 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 export const MKTERSWINGMAN_PAT_ENV = "MKTERSWINGMAN_PAT";
 export const PAT_LOGIN_URL = "https://mkterswingman.com/pat/login";
 const DEFAULT_AUTH_URL = "https://mkterswingman.com";
 const REFRESH_SKEW_MS = 60_000;
+const REFRESH_LOCK_STALE_MS = 30_000;
+const REFRESH_LOCK_TIMEOUT_MS = 90_000;
+const REFRESH_LOCK_POLL_MS = 50;
 export function getAuthStatus(options) {
     if (options.env?.[MKTERSWINGMAN_PAT_ENV]) {
         return {
@@ -54,26 +57,35 @@ export async function getValidToken(options) {
         return null;
     if (auth.type === "pat")
         return auth.pat || null;
-    if (auth.access_token && auth.expires_at && Date.now() + REFRESH_SKEW_MS < auth.expires_at) {
+    if (hasUsableAccessToken(auth, options.now)) {
         return auth.access_token;
     }
-    if (!auth.refresh_token)
-        return null;
-    const refreshed = await refreshJwt(auth.refresh_token, {
-        clientId: auth.client_id,
-        authUrl: options.authUrl,
-        fetchImpl: options.fetchImpl
-    });
-    if (!refreshed)
-        return null;
-    writeSharedAuth(options.authJsonPath, {
-        type: "jwt",
-        access_token: refreshed.access_token,
-        refresh_token: refreshed.refresh_token,
-        expires_at: Date.now() + refreshed.expires_in * 1000,
-        client_id: auth.client_id
+    return withRefreshLock(options, async () => {
+        const latest = readSharedAuth(options.authJsonPath);
+        if (!latest)
+            return null;
+        if (latest.type === "pat")
+            return latest.pat || null;
+        if (hasUsableAccessToken(latest, options.now))
+            return latest.access_token;
+        if (!latest.refresh_token)
+            return null;
+        const refreshed = await refreshJwt(latest.refresh_token, {
+            clientId: latest.client_id,
+            authUrl: options.authUrl,
+            fetchImpl: options.fetchImpl
+        });
+        if (!refreshed)
+            return null;
+        writeSharedAuth(options.authJsonPath, {
+            type: "jwt",
+            access_token: refreshed.access_token,
+            refresh_token: refreshed.refresh_token,
+            expires_at: (options.now ?? Date.now)() + refreshed.expires_in * 1000,
+            client_id: latest.client_id
+        });
+        return refreshed.access_token;
     });
-    return refreshed.access_token;
 }
 export function savePat(authJsonPath, pat) {
     const normalized = pat.trim();
@@ -112,6 +124,95 @@ export function writeSharedAuth(authJsonPath, data) {
         // Windows may ignore POSIX modes.
     }
 }
+function hasUsableAccessToken(auth, now) {
+    return Boolean(auth.access_token &&
+        auth.expires_at &&
+        (now ?? Date.now)() + REFRESH_SKEW_MS < auth.expires_at);
+}
+async function withRefreshLock(options, fn) {
+    const lockPath = `${options.authJsonPath}.refresh.lock`;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = now() + REFRESH_LOCK_TIMEOUT_MS;
+    mkdirSync(dirname(options.authJsonPath), { recursive: true });
+    while (true) {
+        try {
+            mkdirSync(lockPath, { mode: 0o700 });
+            try {
+                writeLockOwner(lockPath, now());
+            }
+            catch (error) {
+                rmSync(lockPath, { recursive: true, force: true });
+                throw error;
+            }
+            try {
+                return await fn();
+            }
+            finally {
+                rmSync(lockPath, { recursive: true, force: true });
+            }
+        }
+        catch (error) {
+            if (!isAlreadyExistsError(error))
+                throw error;
+            if (canRecoverRefreshLock(lockPath, now())) {
+                rmSync(lockPath, { recursive: true, force: true });
+                continue;
+            }
+            if (now() >= deadline) {
+                throw new Error("Timed out waiting for mkterswingman auth refresh lock");
+            }
+            await sleep(REFRESH_LOCK_POLL_MS);
+        }
+    }
+}
+function isAlreadyExistsError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "EEXIST");
+}
+function writeLockOwner(lockPath, createdAtMs) {
+    writeFileSync(`${lockPath}/owner.json`, JSON.stringify({ pid: process.pid, created_at: createdAtMs }), { encoding: "utf8", mode: 0o600 });
+}
+function canRecoverRefreshLock(lockPath, nowMs) {
+    const owner = readRefreshLockOwner(lockPath);
+    if (owner) {
+        return nowMs - owner.created_at > REFRESH_LOCK_STALE_MS && !isProcessAlive(owner.pid);
+    }
+    try {
+        return nowMs - statSync(lockPath).mtimeMs > REFRESH_LOCK_STALE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+function readRefreshLockOwner(lockPath) {
+    try {
+        const owner = JSON.parse(readFileSync(`${lockPath}/owner.json`, "utf8"));
+        if (typeof owner.pid === "number" && typeof owner.created_at === "number") {
+            return { pid: owner.pid, created_at: owner.created_at };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "EPERM");
+    }
+}
 async function refreshJwt(refreshToken, options) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const response = await fetchImpl(`${options.authUrl ?? DEFAULT_AUTH_URL}/oauth/token`, {

package/dist/cli.d.ts

@@ -8,6 +8,7 @@ export interface CliContext {
     stderr?: (message: string) => void;
     stdin?: AsyncIterable<Buffer | string>;
     fetchImpl?: typeof fetch;
+    openUrlImpl?: (url: string) => void | Promise<void>;
     spawnSyncImpl?: typeof spawnSync;
 }
 export declare function runCli(context?: CliContext): Promise<number>;

package/dist/cli.js

@@ -3,7 +3,9 @@ import { readFileSync, realpathSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getAuthStatus, logout, PAT_LOGIN_URL, savePat } from "./auth.js";
+import { getAuthStatus, getValidToken, logout, PAT_LOGIN_URL, savePat } from "./auth.js";
+import { readJobLedger, reconcileWatchLedger } from "./jobLedger.js";
+import { runOAuthLogin } from "./oauthLogin.js";
 import { resolveTwinklerPaths } from "./paths.js";
 import { installBundledSkills } from "./skillInstall.js";
 import { callTwinkler } from "./twinklerClient.js";
@@ -15,18 +17,20 @@ const HELP = [
     "  twinkler login",
     "  twinkler ensure [--auto-update] [--json]",
     "  twinkler auth status",
-    "  twinkler auth login --pat-stdin",
+    "  twinkler auth login",
     "  twinkler call <GET|POST|DELETE> /api/v1/... [--query k=v] [--json '{...}']",
-    "  twinkler jobs active|recent|show <job_id>",
+    "  twinkler jobs active|recent|show <job_id>|ledger",
     "  twinkler update",
     "  twinkler version",
     "",
     "Repair / advanced:",
     "  twinkler setup",
     "  twinkler install-skills",
+    "  twinkler login --pat-stdin",
+    "  twinkler auth login --pat-stdin",
     "  twinkler auth login --pat <TOKEN>",
     "",
-    "mkterswingman PAT:",
+    "PAT fallback:",
     `  ${PAT_LOGIN_URL}`
 ].join("\n");
 const PACKAGE_NAME = "@mkterswingman/5mghost-twinkler";
@@ -51,20 +55,30 @@ export async function runCli(context = {}) {
                 out(readPackageVersion());
                 return 0;
             case "auth":
-                return await runAuthCommand(args, { paths, env, out, stdin: context.stdin ?? process.stdin });
+                return await runAuthCommand(args, {
+                    paths,
+                    env,
+                    out,
+                    stdin: context.stdin ?? process.stdin,
+                    fetchImpl: context.fetchImpl,
+                    openUrlImpl: context.openUrlImpl
+                });
             case "login":
-                return await runAuthCommand(["login", "--pat-stdin", ...args.filter((arg) => arg !== "--pat-stdin")], {
+                return await runAuthCommand(["login", ...args], {
                     paths,
                     env,
                     out,
-                    stdin: context.stdin ?? process.stdin
+                    stdin: context.stdin ?? process.stdin,
+                    fetchImpl: context.fetchImpl,
+                    openUrlImpl: context.openUrlImpl
                 });
             case "ensure":
-                return runEnsureCommand(args, {
+                return await runEnsureCommand(args, {
                     paths,
                     env,
                     out,
                     err,
+                    fetchImpl: context.fetchImpl,
                     spawnSyncImpl: context.spawnSyncImpl ?? spawnSync
                 });
             case "call": {
@@ -75,6 +89,7 @@ export async function runCli(context = {}) {
                     env,
                     fetchImpl: context.fetchImpl
                 });
+                reconcileCallResult(paths.jobsLedgerPath, result, parsed);
                 out(JSON.stringify(result, null, 2));
                 return 0;
             }
@@ -92,13 +107,13 @@ export async function runCli(context = {}) {
             }
             case "setup": {
                 const results = installBundledSkills({ homeDir: paths.homeDir });
-                const auth = getAuthStatus({ authJsonPath: paths.authJsonPath, env });
+                const auth = await getVerifiedAuthStatus(paths, env, context.fetchImpl);
                 out([
                     "Twinkler setup",
                     renderSkillInstallResults(results),
                     auth.authenticated
                         ? `Auth: ready (${auth.type} via ${auth.source})`
-                        : `Auth: missing. Ask the user to open ${PAT_LOGIN_URL}, then enter the mkterswingman PAT into 'twinkler auth login --pat-stdin'. Do not paste PATs into chat.`
+                        : "Auth: missing. Run 'twinkler login' and complete the browser login."
                 ].join("\n"));
                 return results.some((result) => result.status === "error") ? 1 : 0;
             }
@@ -106,7 +121,7 @@ export async function runCli(context = {}) {
             case "upgrade":
                 return runUpdateCommand(args, { env, out, err, spawnSyncImpl: context.spawnSyncImpl ?? spawnSync });
             case "doctor": {
-                const auth = getAuthStatus({ authJsonPath: paths.authJsonPath, env });
+                const auth = await getVerifiedAuthStatus(paths, env, context.fetchImpl);
                 out([
                     "Twinkler doctor",
                     `Node: ${process.version}`,
@@ -134,10 +149,11 @@ async function runAuthCommand(args, context) {
         context.out([
             "Usage:",
             "  twinkler auth status",
-            "  twinkler auth login --pat-stdin",
+            "  twinkler auth login",
             "  twinkler auth logout",
             "",
-            "Advanced compatibility:",
+            "Advanced PAT compatibility:",
+            "  twinkler auth login --pat-stdin",
             "  twinkler auth login --pat <TOKEN>",
             "",
             `PAT page: ${PAT_LOGIN_URL}`
@@ -145,11 +161,11 @@ async function runAuthCommand(args, context) {
         return 0;
     }
     if (subcommand === "status") {
-        const status = getAuthStatus({ authJsonPath: context.paths.authJsonPath, env: context.env });
+        const status = await getVerifiedAuthStatus(context.paths, context.env, context.fetchImpl);
         if (!status.authenticated) {
             context.out([
                 "Not logged in.",
-                `Open ${PAT_LOGIN_URL}, copy the mkterswingman PAT, and enter it into 'twinkler auth login --pat-stdin'. Do not paste PATs into chat.`
+                "Run 'twinkler login' and complete the browser login. Advanced fallback: 'twinkler login --pat-stdin'."
             ].join("\n"));
             return 1;
         }
@@ -169,14 +185,16 @@ async function runAuthCommand(args, context) {
     if (subcommand === "login") {
         const patFlagIndex = args.indexOf("--pat");
         const patStdin = args.includes("--pat-stdin");
-        const token = patStdin ? await readAllStdin(context.stdin) : args[patFlagIndex + 1];
         if (patFlagIndex === -1 && !patStdin) {
-            context.out([
-                "mkterswingman PAT is required.",
-                `Open ${PAT_LOGIN_URL}, copy the PAT, then enter it into 'twinkler auth login --pat-stdin'. Do not paste PATs into chat.`
-            ].join("\n"));
-            return 1;
+            await runOAuthLogin({
+                authJsonPath: context.paths.authJsonPath,
+                fetchImpl: context.fetchImpl,
+                openUrlImpl: context.openUrlImpl,
+                out: context.out
+            });
+            return 0;
         }
+        const token = patStdin ? await readAllStdin(context.stdin) : args[patFlagIndex + 1];
         savePat(context.paths.authJsonPath, token ?? "");
         context.out("mkterswingman PAT saved.");
         return 0;
@@ -184,12 +202,12 @@ async function runAuthCommand(args, context) {
     context.out(`Unknown auth subcommand: ${subcommand}`);
     return 1;
 }
-function runEnsureCommand(args, context) {
+async function runEnsureCommand(args, context) {
     const json = args.includes("--json");
     const autoUpdate = args.includes("--auto-update");
     const localVersion = readPackageVersion();
     const latest = readNpmLatestVersion(context.spawnSyncImpl, context.env);
-    const auth = getAuthStatus({ authJsonPath: context.paths.authJsonPath, env: context.env });
+    const auth = await getVerifiedAuthStatus(context.paths, context.env, context.fetchImpl);
     const updateNeeded = latest.version !== null && compareSemver(latest.version, localVersion) > 0;
     let update = {
         needed: updateNeeded,
@@ -242,6 +260,13 @@ function runEnsureCommand(args, context) {
         context.err(update.error);
     return exitCode;
 }
+async function getVerifiedAuthStatus(paths, env, fetchImpl) {
+    const auth = getAuthStatus({ authJsonPath: paths.authJsonPath, env });
+    if (!auth.authenticated)
+        return auth;
+    const token = await getValidToken({ authJsonPath: paths.authJsonPath, env, fetchImpl });
+    return { ...auth, authenticated: Boolean(token) };
+}
 function renderEnsureResult(result) {
     const latest = result.latest_version ?? `unknown (${result.latest_check.ok ? "not checked" : result.latest_check.error})`;
     const lines = [
@@ -289,6 +314,10 @@ function parseSemver(version) {
 async function runJobsCommand(args, context) {
     const [subcommand, value] = args.filter((arg) => arg !== "--json");
     let path;
+    if (subcommand === "ledger" || subcommand === "local") {
+        context.out(JSON.stringify(readJobLedger(context.paths.jobsLedgerPath), null, 2));
+        return 0;
+    }
     if (subcommand === "active") {
         path = "/api/v1/twitch/watch";
     }
@@ -303,7 +332,8 @@ async function runJobsCommand(args, context) {
             "Usage:",
             "  twinkler jobs active",
             "  twinkler jobs recent",
-            "  twinkler jobs show <job_id>"
+            "  twinkler jobs show <job_id>",
+            "  twinkler jobs ledger"
         ].join("\n"));
         return 1;
     }
@@ -316,6 +346,7 @@ async function runJobsCommand(args, context) {
         env: context.env,
         fetchImpl: context.fetchImpl
     });
+    reconcileWatchLedger(context.paths.jobsLedgerPath, result, { source: `jobs ${subcommand}` });
     context.out(JSON.stringify(result, null, 2));
     return 0;
 }
@@ -326,6 +357,7 @@ function parseCallArgs(args) {
     }
     const query = {};
     let jsonBody;
+    let userIntent = null;
     for (let index = 0; index < rest.length; index += 1) {
         const arg = rest[index];
         if (arg === "--query") {
@@ -345,9 +377,26 @@ function parseCallArgs(args) {
             jsonBody = JSON.parse(raw.startsWith("@") ? readFileSync(raw.slice(1), "utf8") : raw);
             continue;
         }
+        if (arg === "--intent") {
+            const raw = rest[++index];
+            if (!raw)
+                throw new Error("--intent expects a short description");
+            userIntent = raw;
+            continue;
+        }
         throw new Error(`Unknown call option: ${arg}`);
     }
-    return { method, path, query, jsonBody };
+    return { method, path, query, jsonBody, userIntent };
+}
+function reconcileCallResult(ledgerPath, result, parsed) {
+    const normalizedPath = parsed.path.startsWith("/") ? parsed.path : `/${parsed.path}`;
+    if (!normalizedPath.startsWith("/api/v1/twitch/watch"))
+        return;
+    reconcileWatchLedger(ledgerPath, result, {
+        source: `call ${parsed.method.toUpperCase()} ${normalizedPath}`,
+        requestBody: parsed.jsonBody,
+        userIntent: parsed.userIntent
+    });
 }
 function renderSkillInstallResults(results) {
     return [

package/dist/jobLedger.d.ts

@@ -0,0 +1,31 @@
+export interface WatchJobLedger {
+    version: 1;
+    jobs: WatchJobLedgerRecord[];
+}
+export interface WatchJobLedgerRecord {
+    job_id: string;
+    created_at: string;
+    updated_at: string;
+    user_intent: string | null;
+    logins: string[];
+    collect: string[];
+    start: unknown;
+    stop: unknown;
+    status: string;
+    last_seen_at: string;
+    last_counts: {
+        ccv_points: number | null;
+        chat_messages: number | null;
+    };
+    latest_ccv: unknown;
+    source: string;
+    server: unknown;
+}
+export declare function readJobLedger(path: string): WatchJobLedger;
+export declare function writeJobLedger(path: string, ledger: WatchJobLedger): void;
+export declare function reconcileWatchLedger(ledgerPath: string, response: unknown, options?: {
+    source: string;
+    requestBody?: unknown;
+    userIntent?: string | null;
+    now?: () => Date;
+}): void;

package/dist/jobLedger.js

@@ -0,0 +1,154 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export function readJobLedger(path) {
+    if (!existsSync(path))
+        return emptyLedger();
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed.version !== 1 || !Array.isArray(parsed.jobs))
+            return emptyLedger();
+        return {
+            version: 1,
+            jobs: parsed.jobs.flatMap((job) => normalizeLedgerRecord(job))
+        };
+    }
+    catch {
+        return emptyLedger();
+    }
+}
+export function writeJobLedger(path, ledger) {
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+        chmodSync(dirname(path), 0o700);
+    }
+    catch {
+        // Windows may ignore POSIX modes.
+    }
+    const tmpPath = `${path}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(ledger, null, 2), { encoding: "utf8", mode: 0o600 });
+    renameSync(tmpPath, path);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Windows may ignore POSIX modes.
+    }
+}
+export function reconcileWatchLedger(ledgerPath, response, options = { source: "unknown" }) {
+    const records = extractWatchRecords(response, options);
+    if (records.length === 0)
+        return;
+    const ledger = readJobLedger(ledgerPath);
+    const byId = new Map(ledger.jobs.map((job) => [job.job_id, job]));
+    for (const record of records) {
+        const existing = byId.get(record.job_id);
+        byId.set(record.job_id, mergeRecord(existing, record));
+    }
+    writeJobLedger(ledgerPath, {
+        version: 1,
+        jobs: [...byId.values()].sort((a, b) => b.updated_at.localeCompare(a.updated_at))
+    });
+}
+function extractWatchRecords(response, options) {
+    const envelope = asRecord(response);
+    const data = asRecord(envelope?.data);
+    if (!data)
+        return [];
+    const nowIso = (options.now ?? (() => new Date()))().toISOString();
+    if (Array.isArray(data.jobs)) {
+        return data.jobs.flatMap((job) => buildRecord(asRecord(job), options, nowIso));
+    }
+    return buildRecord(data, options, nowIso);
+}
+function buildRecord(data, options, nowIso) {
+    if (!data || typeof data.job_id !== "string")
+        return [];
+    const requestBody = asRecord(options.requestBody);
+    const accumulated = asRecord(data.accumulated);
+    return [{
+            job_id: data.job_id,
+            created_at: typeof data.created_at === "string" ? data.created_at : nowIso,
+            updated_at: nowIso,
+            user_intent: options.userIntent ?? null,
+            logins: stringArray(data.logins ?? requestBody?.logins),
+            collect: stringArray(data.collect ?? requestBody?.collect),
+            start: data.start ?? requestBody?.start ?? null,
+            stop: data.stop ?? requestBody?.stop ?? null,
+            status: typeof data.status === "string" ? data.status : "unknown",
+            last_seen_at: nowIso,
+            last_counts: {
+                ccv_points: numberOrNull(accumulated?.ccv_points),
+                chat_messages: numberOrNull(accumulated?.chat_messages)
+            },
+            latest_ccv: data.latest_ccv ?? null,
+            source: options.source,
+            server: data
+        }];
+}
+function mergeRecord(existing, next) {
+    if (!existing)
+        return next;
+    return {
+        ...existing,
+        ...next,
+        user_intent: next.user_intent ?? existing.user_intent,
+        logins: next.logins.length > 0 ? next.logins : existing.logins,
+        collect: next.collect.length > 0 ? next.collect : existing.collect,
+        start: next.start ?? existing.start,
+        stop: next.stop ?? existing.stop,
+        last_counts: {
+            ccv_points: next.last_counts.ccv_points ?? existing.last_counts.ccv_points,
+            chat_messages: next.last_counts.chat_messages ?? existing.last_counts.chat_messages
+        },
+        latest_ccv: next.latest_ccv ?? existing.latest_ccv
+    };
+}
+function emptyLedger() {
+    return { version: 1, jobs: [] };
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function numberOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function normalizeLedgerRecord(value) {
+    const record = asRecord(value);
+    if (!record ||
+        typeof record.job_id !== "string" ||
+        typeof record.created_at !== "string" ||
+        typeof record.updated_at !== "string" ||
+        typeof record.status !== "string" ||
+        typeof record.last_seen_at !== "string" ||
+        !Array.isArray(record.logins) ||
+        !Array.isArray(record.collect)) {
+        return [];
+    }
+    const counts = asRecord(record.last_counts);
+    return [{
+            job_id: record.job_id,
+            created_at: record.created_at,
+            updated_at: record.updated_at,
+            user_intent: typeof record.user_intent === "string" ? record.user_intent : null,
+            logins: stringArray(record.logins),
+            collect: stringArray(record.collect),
+            start: record.start ?? null,
+            stop: record.stop ?? null,
+            status: record.status,
+            last_seen_at: record.last_seen_at,
+            last_counts: {
+                ccv_points: numberOrNull(counts?.ccv_points),
+                chat_messages: numberOrNull(counts?.chat_messages)
+            },
+            latest_ccv: record.latest_ccv ?? null,
+            source: typeof record.source === "string" ? record.source : "unknown",
+            server: record.server ?? null
+        }];
+}

package/dist/oauthLogin.d.ts

@@ -0,0 +1,11 @@
+export interface OAuthLoginOptions {
+    authJsonPath: string;
+    authUrl?: string;
+    clientName?: string;
+    fetchImpl?: typeof fetch;
+    openUrlImpl?: (url: string) => void | Promise<void>;
+    timeoutMs?: number;
+    out?: (message: string) => void;
+    now?: () => number;
+}
+export declare function runOAuthLogin(options: OAuthLoginOptions): Promise<void>;

package/dist/oauthLogin.js

@@ -0,0 +1,247 @@
+import { createHash, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { writeSharedAuth } from "./auth.js";
+const DEFAULT_AUTH_URL = "https://mkterswingman.com";
+const DEFAULT_SCOPE = "openid profile email mcp:use";
+const DEFAULT_TIMEOUT_MS = 300_000;
+export async function runOAuthLogin(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const authUrl = (options.authUrl ?? DEFAULT_AUTH_URL).replace(/\/+$/, "");
+    const out = options.out ?? (() => undefined);
+    const now = options.now ?? Date.now;
+    const codeVerifier = token(32);
+    const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
+    const state = token(32);
+    let server = null;
+    try {
+        server = createServer();
+        const redirectUri = await listenOnLoopback(server);
+        const registered = await registerClient(fetchImpl, authUrl, {
+            clientName: options.clientName ?? "5mghost-twinkler-cli",
+            redirectUri
+        });
+        const callback = waitForCallback({
+            server,
+            state,
+            authUrl,
+            redirectUri,
+            clientId: registered.client_id,
+            clientSecret: registered.client_secret,
+            codeVerifier,
+            fetchImpl
+        });
+        const authorizeUrl = buildAuthorizeUrl(authUrl, {
+            clientId: registered.client_id,
+            redirectUri,
+            codeChallenge,
+            state
+        });
+        out("Opening browser for mkterswingman login.");
+        out(authorizeUrl);
+        try {
+            await (options.openUrlImpl ?? openUrl)(authorizeUrl);
+        }
+        catch {
+            out("Could not open the browser automatically. Open the URL above to continue login.");
+        }
+        const tokens = await withTimeout(callback, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        writeSharedAuth(options.authJsonPath, {
+            type: "jwt",
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token,
+            expires_at: now() + tokens.expires_in * 1000,
+            client_id: registered.client_id
+        });
+        out("mkterswingman OAuth login saved.");
+    }
+    finally {
+        if (server) {
+            await closeServer(server);
+        }
+    }
+}
+async function registerClient(fetchImpl, authUrl, input) {
+    const response = await fetchImpl(`${authUrl}/oauth/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({
+            client_name: input.clientName,
+            redirect_uris: [input.redirectUri],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            scope: DEFAULT_SCOPE
+        })
+    });
+    const body = await readJson(response);
+    if (!response.ok) {
+        throw new Error(`OAuth client registration failed: HTTP ${response.status} ${summarize(body)}`);
+    }
+    const clientId = stringField(body, "client_id");
+    return {
+        client_id: clientId,
+        client_secret: typeof body.client_secret === "string" ? body.client_secret : undefined
+    };
+}
+function waitForCallback(input) {
+    let settled = false;
+    return new Promise((resolve, reject) => {
+        input.server.on("request", async (req, res) => {
+            if (settled) {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<h1>Login already completed</h1>");
+                return;
+            }
+            const url = new URL(req.url ?? "/", input.redirectUri);
+            if (url.pathname !== new URL(input.redirectUri).pathname) {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<h1>Waiting for authorization...</h1>");
+                return;
+            }
+            const error = url.searchParams.get("error");
+            if (error) {
+                settled = true;
+                res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(`<h1>Authorization failed</h1><p>${escapeHtml(error)}</p>`);
+                reject(new Error(`OAuth error: ${error}`));
+                return;
+            }
+            const code = url.searchParams.get("code");
+            if (!code) {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<h1>Waiting for authorization...</h1>");
+                return;
+            }
+            if (url.searchParams.get("state") !== input.state) {
+                settled = true;
+                res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<h1>Authorization failed</h1><p>State mismatch.</p>");
+                reject(new Error("OAuth state mismatch"));
+                return;
+            }
+            try {
+                const tokens = await exchangeCode(input, code);
+                settled = true;
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<h1>Login complete</h1><p>You can close this window.</p>");
+                resolve(tokens);
+            }
+            catch (error) {
+                settled = true;
+                res.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<h1>Token exchange failed</h1>");
+                reject(error);
+            }
+        });
+    });
+}
+async function exchangeCode(input, code) {
+    const response = await input.fetchImpl(`${input.authUrl}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: input.redirectUri,
+            client_id: input.clientId,
+            code_verifier: input.codeVerifier,
+            ...(input.clientSecret ? { client_secret: input.clientSecret } : {})
+        })
+    });
+    const body = await readJson(response);
+    if (!response.ok) {
+        throw new Error(`OAuth token exchange failed: HTTP ${response.status} ${summarize(body)}`);
+    }
+    const accessToken = stringField(body, "access_token");
+    const refreshToken = stringField(body, "refresh_token");
+    const expiresIn = typeof body.expires_in === "number" ? body.expires_in : Number(body.expires_in);
+    if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+        throw new Error("OAuth token exchange response missing expires_in");
+    }
+    return { access_token: accessToken, refresh_token: refreshToken, expires_in: expiresIn };
+}
+function buildAuthorizeUrl(authUrl, input) {
+    const url = new URL(`${authUrl}/oauth/authorize`);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", input.clientId);
+    url.searchParams.set("redirect_uri", input.redirectUri);
+    url.searchParams.set("code_challenge", input.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("state", input.state);
+    url.searchParams.set("scope", DEFAULT_SCOPE);
+    return url.toString();
+}
+function listenOnLoopback(server) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                reject(new Error("Failed to bind OAuth callback server"));
+                return;
+            }
+            resolve(`http://127.0.0.1:${address.port}/callback`);
+        });
+    });
+}
+function withTimeout(promise, timeoutMs) {
+    let timeout;
+    const timer = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => reject(new Error(`OAuth login timed out after ${Math.ceil(timeoutMs / 1000)} seconds`)), timeoutMs);
+    });
+    return Promise.race([promise, timer]).finally(() => {
+        if (timeout)
+            clearTimeout(timeout);
+    });
+}
+async function readJson(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+function stringField(body, field) {
+    const value = body[field];
+    if (typeof value !== "string" || !value) {
+        throw new Error(`OAuth response missing ${field}`);
+    }
+    return value;
+}
+function summarize(body) {
+    if (typeof body.error_description === "string")
+        return body.error_description;
+    if (typeof body.error === "string")
+        return body.error;
+    if (typeof body.raw === "string")
+        return body.raw.slice(0, 200);
+    return JSON.stringify(body).slice(0, 200);
+}
+function openUrl(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "darwin" ? [url] : process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.unref();
+}
+function token(bytes) {
+    return randomBytes(bytes).toString("base64url");
+}
+function closeServer(server) {
+    return new Promise((resolve) => {
+        server.close(() => resolve());
+        server.once("error", () => resolve());
+    });
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}

package/dist/paths.d.ts

@@ -5,6 +5,8 @@ export interface TwinklerPaths {
     homeDir: string;
     mkterswingmanDir: string;
     authJsonPath: string;
+    twinklerDir: string;
+    jobsLedgerPath: string;
     skillsManifestPath: string;
 }
 export declare function resolveTwinklerPaths(options?: PathOptions): TwinklerPaths;

package/dist/paths.js

@@ -8,6 +8,8 @@ export function resolveTwinklerPaths(options = {}) {
         homeDir,
         mkterswingmanDir: join(homeDir, ".mkterswingman"),
         authJsonPath: join(homeDir, ".mkterswingman", "auth.json"),
+        twinklerDir: join(homeDir, ".mkterswingman", "twinkler"),
+        jobsLedgerPath: join(homeDir, ".mkterswingman", "twinkler", "jobs.json"),
         skillsManifestPath: resolveBundledAssetPath("skills.manifest.json")
     };
 }

package/dist/twinklerClient.js

@@ -9,7 +9,7 @@ export async function callTwinkler(options) {
         fetchImpl: options.fetchImpl
     });
     if (!token) {
-        throw new Error(`Missing mkterswingman auth. Ask the user to open https://mkterswingman.com/pat/login, then save the PAT with 'twinkler auth login --pat-stdin' or set ${MKTERSWINGMAN_PAT_ENV}.`);
+        throw new Error(`Missing mkterswingman auth. Run 'twinkler login' and complete the browser login. Advanced fallback: run 'twinkler login --pat-stdin' or set ${MKTERSWINGMAN_PAT_ENV}.`);
     }
     const url = buildUrl(path, options.query ?? {});
     const response = await (options.fetchImpl ?? fetch)(url, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/5mghost-twinkler",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Lightweight AI helper for the 5mghost Twinkler API",
   "type": "module",
   "engines": {

package/skills/use-5mghost-twinkler/SKILL.md

@@ -29,9 +29,9 @@ Read the JSON.
 - If `update.status` is `updated`, continue the current task. Tell the user only
   that the helper is updated and a new AI session is needed to load changed skill
   text.
-- If auth is missing or expired, run `twinkler login`, give the user
-  <https://mkterswingman.com/pat/login>, and have them paste the PAT into local
-  stdin. Never ask for the PAT in chat.
+- If auth is missing or expired, run `twinkler login`. It opens the browser
+  OAuth login and stores a refreshable local token. Use PAT only as an advanced
+  fallback: run `twinkler login --pat-stdin` if browser login is unavailable.
 - If update failed but the current helper can still complete the task, continue
   and mention the update failure briefly. Stop only when the helper is too old
   for the requested command.
@@ -70,16 +70,26 @@ collect chat messages, or stop when the stream ends or changes game.
 Before creating a new watch job in a new session, recover existing work:
 
 ```bash
+twinkler jobs ledger
 twinkler jobs active
 twinkler jobs recent
 ```
 
+The local job ledger lives at `~/.mkterswingman/twinkler/jobs.json`. It is the
+cross-session memory for watch jobs. Always inspect it before creating another
+job when the user asks about monitoring, pending results, "上次那个 job", or any
+vague live-watch status.
+
 Create a job:
 
 ```bash
-twinkler call POST /api/v1/twitch/watch --json '{"logins":["theburntpeanut"],"collect":["ccv","chat"],"start":{"type":"time","at":"now"},"stop":{"type":"game","game_name":"ARC Raiders"}}'
+twinkler call POST /api/v1/twitch/watch --intent "盯 theburntpeanut until stream ends or no longer ARC Raiders" --json '{"logins":["theburntpeanut"],"collect":["ccv","chat"],"start":{"type":"time","at":"now"},"stop":{"type":"game","game_name":"ARC Raiders"}}'
 ```
 
+Use `--intent` for the user's plain-language goal. The helper does not send it
+to Twinkler; it stores it only in the local ledger so a later AI session can
+understand which job is which and when it should stop.
+
 Then inspect it with:
 
 ```bash
@@ -88,20 +98,19 @@ twinkler call GET /api/v1/twitch/watch/<job_id>/ccv
 twinkler call GET /api/v1/twitch/watch/<job_id>/chat
 ```
 
-For long-running jobs, create a monitor in the AI environment. Generate the
-portable monitor payload with the bundled script in this skill directory:
-
-```bash
-node scripts/create-watch-monitor.mjs --job-id <job_id> --cadence-min 10 --stop "stream ended or no longer matches requested game"
-```
+Do not make the user remember job IDs or recovery commands. Use the ledger and
+hosted jobs endpoints yourself in new sessions. If the AI runtime has a
+heartbeat/reminder tool, you may use it, but it is optional; the ledger is the
+required recovery mechanism.
 
-If the current runtime has an automation, heartbeat, reminder, or monitor tool,
-submit the generated prompt there. If not, state that proactive notification is
-not available in this environment, but the job can be recovered later with
-`twinkler jobs active` and `twinkler jobs recent`.
+Expected watch result shapes:
 
-Do not make the user remember or run the recovery commands. Use them yourself in
-new sessions.
+- `ccv_points` are live viewer samples. Preserve `login`, timestamp fields,
+  `viewer_count`, `game_id`, `game_name`, `title`, and `online`.
+- `chat_messages` are captured chat rows. Preserve `jobId`, `login`,
+  `senderLogin`, `tmiSentTs`, `msgId`, `text`, `badges`, `color`, and `flags`.
+- Job summaries include `accumulated.ccv_points`,
+  `accumulated.chat_messages`, and often `latest_ccv`.
 
 ## Data Processing Layer
 

package/skills/setup-5mghost-twinkler/SKILL.md

@@ -1,71 +0,0 @@
----
-name: setup-5mghost-twinkler
-preamble-tier: 3
-version: 0.2.0
-description: |
-  Set up or repair the local Twinkler helper, bundled skills, and mkterswingman
-  auth for AI-driven Twitch data workflows.
----
-
-# Setup 5mghost Twinkler
-
-Use when Twinkler is missing, auth is missing or expired, skills may be stale,
-or the user asks to prepare Twinkler for an AI workflow.
-
-## Default Path
-
-1. Check the helper:
-
-```bash
-twinkler doctor
-```
-
-2. If the helper is missing, install it:
-
-```bash
-npm install -g @mkterswingman/5mghost-twinkler
-```
-
-The npm install runs the bundled skill installer automatically. Use `twinkler
-setup` only as a repair command when postinstall could not update the local AI
-skill directories.
-
-3. Repair skills when needed:
-
-```bash
-twinkler setup
-```
-
-4. If auth is missing, send the user to:
-
-```text
-https://mkterswingman.com/pat/login
-```
-
-Ask the user to copy the mkterswingman PAT, then start:
-
-```bash
-twinkler auth login --pat-stdin
-```
-
-Have the user paste the PAT into that local input. Do not ask them to paste the
-PAT into chat, screenshots, docs, shell history, or source files.
-
-## Success
-
-`twinkler doctor` should report auth ready. Then the AI can use the
-`use-5mghost-twinkler` skill and `twinkler call`.
-
-## Recovery
-
-- Missing command: run `npm install -g @mkterswingman/5mghost-twinkler`.
-- Missing skills after install: run `twinkler setup`, then restart the AI session.
-- Missing auth: use the PAT page and `twinkler auth login --pat-stdin`.
-- HTTP 401/403 from API calls: run `twinkler auth status`; if stale, log in again.
-- Permission or npm global install failure: use the same package manager and
-  Node installation method that originally installed global npm packages.
-
-## Secret Policy
-
-Never print, echo, log, commit, or store PATs in project files. The only normal
-local storage is `~/.mkterswingman/auth.json`, written by the helper.

package/skills/use-5mghost-twinkler/scripts/create-watch-monitor.mjs

@@ -1,57 +0,0 @@
-#!/usr/bin/env node
-
-const args = parseArgs(process.argv.slice(2));
-if (!args.jobId) {
-  console.error("Usage: create-watch-monitor.mjs --job-id <job_id> [--cadence-min 10] [--stop text] [--fields ccv_points,chat_messages,latest_ccv]");
-  process.exit(1);
-}
-
-const cadenceMin = Number.parseInt(args.cadenceMin ?? "10", 10);
-if (!Number.isFinite(cadenceMin) || cadenceMin < 1) {
-  console.error("--cadence-min must be a positive integer");
-  process.exit(1);
-}
-
-const fields = (args.fields ?? "ccv_points,chat_messages,latest_ccv")
-  .split(",")
-  .map((field) => field.trim())
-  .filter(Boolean);
-const stop = args.stop ?? "the watch job completes, expires, is cancelled, the stream ends, or the requested game no longer matches";
-const jobId = args.jobId;
-
-const prompt = [
-  `Check the production 5mghost-twinkler watch job ${jobId}.`,
-  "Do not print secrets.",
-  "Run `twinkler ensure --auto-update --json` first; if auth is missing, ask the user to complete `twinkler login`.",
-  `Fetch \`twinkler jobs show ${jobId}\` and report status plus ${fields.join(", ")}.`,
-  "If the job is active, include latest online/game/title/viewer count when available.",
-  `Stop monitoring when ${stop}.`,
-  "If the job has completed, tell the user clearly that the monitor can be disabled."
-].join(" ");
-
-const payload = {
-  kind: "twinkler_watch_monitor",
-  job_id: jobId,
-  cadence_minutes: cadenceMin,
-  stop_condition: stop,
-  fields,
-  prompt
-};
-
-console.log(JSON.stringify(payload, null, 2));
-
-function parseArgs(argv) {
-  const parsed = {};
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (arg === "--job-id") parsed.jobId = argv[++index];
-    else if (arg === "--cadence-min") parsed.cadenceMin = argv[++index];
-    else if (arg === "--stop") parsed.stop = argv[++index];
-    else if (arg === "--fields") parsed.fields = argv[++index];
-    else {
-      console.error(`Unknown option: ${arg}`);
-      process.exit(1);
-    }
-  }
-  return parsed;
-}