@mkterswingman/5mghost-twinkler 0.1.0

package/README.md

@@ -0,0 +1,13 @@
+# 5mghost Twinkler Helper
+
+Lightweight AI runtime for the hosted Twinkler API.
+
+```bash
+npm install -g @mkterswingman/5mghost-twinkler
+twinkler setup
+twinkler call GET /api/v1/channel/ibai/summary --query days=30
+```
+
+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 auth login --pat-stdin`; do not paste PATs into AI chat.

package/dist/auth.d.ts

@@ -0,0 +1,30 @@
+export declare const MKTERSWINGMAN_PAT_ENV = "MKTERSWINGMAN_PAT";
+export declare const PAT_LOGIN_URL = "https://mkterswingman.com/pat/login";
+export type SharedAuthData = {
+    type: "pat";
+    pat: string;
+} | {
+    type: "jwt";
+    access_token?: string;
+    refresh_token?: string;
+    expires_at?: number;
+    client_id?: string;
+};
+export interface AuthStatus {
+    authenticated: boolean;
+    type: "pat" | "jwt" | null;
+    source: "env" | "shared_auth" | null;
+    authJsonPath: string;
+}
+export interface TokenProviderOptions {
+    authJsonPath: string;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    authUrl?: string;
+}
+export declare function getAuthStatus(options: TokenProviderOptions): AuthStatus;
+export declare function getValidToken(options: TokenProviderOptions): Promise<string | null>;
+export declare function savePat(authJsonPath: string, pat: string): void;
+export declare function logout(authJsonPath: string): void;
+export declare function readSharedAuth(authJsonPath: string): SharedAuthData | null;
+export declare function writeSharedAuth(authJsonPath: string, data: SharedAuthData): void;

package/dist/auth.js

@@ -0,0 +1,137 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, 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;
+export function getAuthStatus(options) {
+    if (options.env?.[MKTERSWINGMAN_PAT_ENV]) {
+        return {
+            authenticated: true,
+            type: "pat",
+            source: "env",
+            authJsonPath: options.authJsonPath
+        };
+    }
+    const auth = readSharedAuth(options.authJsonPath);
+    if (!auth) {
+        return {
+            authenticated: false,
+            type: null,
+            source: null,
+            authJsonPath: options.authJsonPath
+        };
+    }
+    if (auth.type === "pat" && auth.pat) {
+        return {
+            authenticated: true,
+            type: "pat",
+            source: "shared_auth",
+            authJsonPath: options.authJsonPath
+        };
+    }
+    if (auth.type === "jwt" && (auth.access_token || auth.refresh_token)) {
+        return {
+            authenticated: true,
+            type: "jwt",
+            source: "shared_auth",
+            authJsonPath: options.authJsonPath
+        };
+    }
+    return {
+        authenticated: false,
+        type: null,
+        source: null,
+        authJsonPath: options.authJsonPath
+    };
+}
+export async function getValidToken(options) {
+    const envPat = options.env?.[MKTERSWINGMAN_PAT_ENV]?.trim();
+    if (envPat)
+        return envPat;
+    const auth = readSharedAuth(options.authJsonPath);
+    if (!auth)
+        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) {
+        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 refreshed.access_token;
+}
+export function savePat(authJsonPath, pat) {
+    const normalized = pat.trim();
+    if (!normalized)
+        throw new Error("mkterswingman PAT is empty");
+    writeSharedAuth(authJsonPath, { type: "pat", pat: normalized });
+}
+export function logout(authJsonPath) {
+    rmSync(authJsonPath, { force: true });
+}
+export function readSharedAuth(authJsonPath) {
+    if (!existsSync(authJsonPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(authJsonPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSharedAuth(authJsonPath, data) {
+    mkdirSync(dirname(authJsonPath), { recursive: true });
+    try {
+        chmodSync(dirname(authJsonPath), 0o700);
+    }
+    catch {
+        // Windows may ignore POSIX modes.
+    }
+    const tmpPath = `${authJsonPath}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2), { encoding: "utf8", mode: 0o600 });
+    renameSync(tmpPath, authJsonPath);
+    try {
+        chmodSync(authJsonPath, 0o600);
+    }
+    catch {
+        // Windows may ignore POSIX modes.
+    }
+}
+async function refreshJwt(refreshToken, options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const response = await fetchImpl(`${options.authUrl ?? DEFAULT_AUTH_URL}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            ...(options.clientId ? { client_id: options.clientId } : {})
+        })
+    });
+    if (!response.ok)
+        return null;
+    const body = (await response.json());
+    if (!body.access_token || !body.refresh_token || typeof body.expires_in !== "number" || !Number.isFinite(body.expires_in)) {
+        return null;
+    }
+    return {
+        access_token: body.access_token,
+        refresh_token: body.refresh_token,
+        expires_in: body.expires_in
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+export interface CliContext {
+    argv?: string[];
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    stdout?: (message: string) => void;
+    stderr?: (message: string) => void;
+    stdin?: AsyncIterable<Buffer | string>;
+    fetchImpl?: typeof fetch;
+}
+export declare function runCli(context?: CliContext): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAuthStatus, logout, PAT_LOGIN_URL, savePat } from "./auth.js";
+import { resolveTwinklerPaths } from "./paths.js";
+import { installBundledSkills } from "./skillInstall.js";
+import { callTwinkler } from "./twinklerClient.js";
+const HELP = [
+    "twinkler",
+    "",
+    "Usage:",
+    "  twinkler setup",
+    "  twinkler install-skills",
+    "  twinkler doctor",
+    "  twinkler auth status",
+    "  twinkler auth login --pat <TOKEN>",
+    "  twinkler auth login --pat-stdin",
+    "  twinkler call <GET|POST|DELETE> /api/v1/... [--query k=v] [--json '{...}']",
+    "  twinkler version",
+    "",
+    "mkterswingman PAT:",
+    `  ${PAT_LOGIN_URL}`
+].join("\n");
+export async function runCli(context = {}) {
+    const argv = context.argv ?? process.argv.slice(2);
+    const env = context.env ?? process.env;
+    const out = context.stdout ?? ((message) => process.stdout.write(`${message}\n`));
+    const err = context.stderr ?? ((message) => process.stderr.write(`${message}\n`));
+    const paths = resolveTwinklerPaths({ homeDir: context.homeDir });
+    const [command, ...args] = argv;
+    try {
+        switch (command) {
+            case undefined:
+            case "help":
+            case "--help":
+            case "-h":
+                out(HELP);
+                return 0;
+            case "version":
+            case "--version":
+            case "-v":
+                out(readPackageVersion());
+                return 0;
+            case "auth":
+                return await runAuthCommand(args, { paths, env, out, stdin: context.stdin ?? process.stdin });
+            case "call": {
+                const parsed = parseCallArgs(args);
+                const result = await callTwinkler({
+                    ...parsed,
+                    authJsonPath: paths.authJsonPath,
+                    env,
+                    fetchImpl: context.fetchImpl
+                });
+                out(JSON.stringify(result, null, 2));
+                return 0;
+            }
+            case "install-skills": {
+                const results = installBundledSkills({ homeDir: paths.homeDir });
+                out(renderSkillInstallResults(results));
+                return results.some((result) => result.status === "error") ? 1 : 0;
+            }
+            case "setup": {
+                const results = installBundledSkills({ homeDir: paths.homeDir });
+                const auth = getAuthStatus({ authJsonPath: paths.authJsonPath, env });
+                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.`
+                ].join("\n"));
+                return results.some((result) => result.status === "error") ? 1 : 0;
+            }
+            case "doctor": {
+                const auth = getAuthStatus({ authJsonPath: paths.authJsonPath, env });
+                out([
+                    "Twinkler doctor",
+                    `Node: ${process.version}`,
+                    `Auth: ${auth.authenticated ? `ready (${auth.type} via ${auth.source})` : "missing"}`,
+                    `Auth file: ${auth.authJsonPath}`,
+                    `PAT page: ${PAT_LOGIN_URL}`,
+                    "Secret policy: do not commit .env files, auth.json, PATs, bearer tokens, or generated secret files to remote repositories."
+                ].join("\n"));
+                return auth.authenticated ? 0 : 1;
+            }
+            default:
+                err(`Unknown command: ${command}`);
+                out(HELP);
+                return 1;
+        }
+    }
+    catch (error) {
+        err(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+async function runAuthCommand(args, context) {
+    const [subcommand] = args;
+    if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+        context.out([
+            "Usage:",
+            "  twinkler auth status",
+            "  twinkler auth login --pat <TOKEN>",
+            "  twinkler auth login --pat-stdin",
+            "  twinkler auth logout",
+            "",
+            `PAT page: ${PAT_LOGIN_URL}`
+        ].join("\n"));
+        return 0;
+    }
+    if (subcommand === "status") {
+        const status = getAuthStatus({ authJsonPath: context.paths.authJsonPath, env: context.env });
+        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.`
+            ].join("\n"));
+            return 1;
+        }
+        context.out([
+            "Logged in.",
+            `Type: ${status.type}`,
+            `Source: ${status.source}`,
+            `Auth file: ${status.authJsonPath}`
+        ].join("\n"));
+        return 0;
+    }
+    if (subcommand === "logout") {
+        logout(context.paths.authJsonPath);
+        context.out("Logged out.");
+        return 0;
+    }
+    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;
+        }
+        savePat(context.paths.authJsonPath, token ?? "");
+        context.out("mkterswingman PAT saved.");
+        return 0;
+    }
+    context.out(`Unknown auth subcommand: ${subcommand}`);
+    return 1;
+}
+function parseCallArgs(args) {
+    const [method, path, ...rest] = args;
+    if (!method || !path) {
+        throw new Error("Usage: twinkler call <GET|POST|DELETE> /api/v1/... [--query k=v] [--json '{...}']");
+    }
+    const query = {};
+    let jsonBody;
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg === "--query") {
+            const pair = rest[++index];
+            if (!pair || !pair.includes("="))
+                throw new Error("--query expects k=v");
+            const [key, ...valueParts] = pair.split("=");
+            const value = valueParts.join("=");
+            query[key] ??= [];
+            query[key].push(value);
+            continue;
+        }
+        if (arg === "--json") {
+            const raw = rest[++index];
+            if (!raw)
+                throw new Error("--json expects a JSON string or @file");
+            jsonBody = JSON.parse(raw.startsWith("@") ? readFileSync(raw.slice(1), "utf8") : raw);
+            continue;
+        }
+        throw new Error(`Unknown call option: ${arg}`);
+    }
+    return { method, path, query, jsonBody };
+}
+function renderSkillInstallResults(results) {
+    return [
+        "Skills:",
+        ...results.map((result) => {
+            const suffix = result.reason ? ` (${result.reason})` : "";
+            return `- ${result.agent}:${result.skill}: ${result.status}${suffix}`;
+        })
+    ].join("\n");
+}
+async function readAllStdin(stdin) {
+    const chunks = [];
+    for await (const chunk of stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+}
+function readPackageVersion() {
+    const dir = dirname(fileURLToPath(import.meta.url));
+    const candidates = [join(dir, "..", "package.json"), join(dir, "..", "..", "package.json")];
+    for (const candidate of candidates) {
+        try {
+            return JSON.parse(readFileSync(candidate, "utf8")).version;
+        }
+        catch {
+            // Continue checking source and packaged layouts.
+        }
+    }
+    return "0.0.0";
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runCli().then((code) => {
+        process.exitCode = code;
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { callTwinkler, DEFAULT_TWINKLER_BASE_URL, type TwinklerCallOptions } from "./twinklerClient.js";
+export { getAuthStatus, MKTERSWINGMAN_PAT_ENV, PAT_LOGIN_URL, savePat } from "./auth.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { callTwinkler, DEFAULT_TWINKLER_BASE_URL } from "./twinklerClient.js";
+export { getAuthStatus, MKTERSWINGMAN_PAT_ENV, PAT_LOGIN_URL, savePat } from "./auth.js";

package/dist/paths.d.ts

@@ -0,0 +1,11 @@
+export interface PathOptions {
+    homeDir?: string;
+}
+export interface TwinklerPaths {
+    homeDir: string;
+    mkterswingmanDir: string;
+    authJsonPath: string;
+    skillsManifestPath: string;
+}
+export declare function resolveTwinklerPaths(options?: PathOptions): TwinklerPaths;
+export declare function resolveBundledAssetPath(fileName: string): string;

package/dist/paths.js

@@ -0,0 +1,23 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+export function resolveTwinklerPaths(options = {}) {
+    const homeDir = options.homeDir ?? homedir();
+    return {
+        homeDir,
+        mkterswingmanDir: join(homeDir, ".mkterswingman"),
+        authJsonPath: join(homeDir, ".mkterswingman", "auth.json"),
+        skillsManifestPath: resolveBundledAssetPath("skills.manifest.json")
+    };
+}
+export function resolveBundledAssetPath(fileName) {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    const sourceLayout = join(moduleDir, "..", fileName);
+    if (existsSync(sourceLayout))
+        return sourceLayout;
+    const devLayout = join(moduleDir, "..", "..", fileName);
+    if (existsSync(devLayout))
+        return devLayout;
+    return sourceLayout;
+}

package/dist/skillInstall.d.ts

@@ -0,0 +1,11 @@
+export interface InstallSkillsOptions {
+    homeDir: string;
+}
+export interface SkillInstallResult {
+    agent: string;
+    skill: string;
+    status: "installed" | "skipped" | "error";
+    targetDir: string;
+    reason?: string;
+}
+export declare function installBundledSkills(options: InstallSkillsOptions): SkillInstallResult[];

package/dist/skillInstall.js

@@ -0,0 +1,58 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { resolveBundledAssetPath } from "./paths.js";
+const TARGETS = [
+    { agent: "codex", skillsDir: ".codex/skills" },
+    { agent: "agents", skillsDir: ".agents/skills" }
+];
+export function installBundledSkills(options) {
+    const manifestPath = resolveBundledAssetPath("skills.manifest.json");
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const packageRoot = dirname(manifestPath);
+    const results = [];
+    for (const skill of manifest.skills) {
+        const sourceDir = join(packageRoot, skill.source);
+        for (const target of TARGETS) {
+            const rootDir = join(options.homeDir, target.skillsDir);
+            const targetDir = join(rootDir, skill.name);
+            try {
+                if (!existsSync(sourceDir)) {
+                    results.push({
+                        agent: target.agent,
+                        skill: skill.name,
+                        status: "error",
+                        targetDir,
+                        reason: `missing bundled skill source ${sourceDir}`
+                    });
+                    continue;
+                }
+                mkdirSync(rootDir, { recursive: true });
+                rmSync(targetDir, { recursive: true, force: true });
+                cpSync(sourceDir, targetDir, { recursive: true });
+                writeFileSync(join(targetDir, ".install-receipt.json"), JSON.stringify({
+                    product: manifest.product,
+                    skill: skill.name,
+                    agent: target.agent,
+                    source: basename(sourceDir),
+                    installed_at: new Date().toISOString()
+                }, null, 2));
+                results.push({
+                    agent: target.agent,
+                    skill: skill.name,
+                    status: "installed",
+                    targetDir
+                });
+            }
+            catch (error) {
+                results.push({
+                    agent: target.agent,
+                    skill: skill.name,
+                    status: "error",
+                    targetDir,
+                    reason: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    }
+    return results;
+}

package/dist/twinklerClient.d.ts

@@ -0,0 +1,11 @@
+export declare const DEFAULT_TWINKLER_BASE_URL = "https://mkterswingman.com/5mghost/twinkler";
+export interface TwinklerCallOptions {
+    method: string;
+    path: string;
+    query?: Record<string, string[]>;
+    jsonBody?: unknown;
+    authJsonPath: string;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+}
+export declare function callTwinkler(options: TwinklerCallOptions): Promise<unknown>;

package/dist/twinklerClient.js

@@ -0,0 +1,71 @@
+import { getValidToken, MKTERSWINGMAN_PAT_ENV } from "./auth.js";
+export const DEFAULT_TWINKLER_BASE_URL = "https://mkterswingman.com/5mghost/twinkler";
+export async function callTwinkler(options) {
+    const method = normalizeMethod(options.method);
+    const path = normalizePath(options.path);
+    const token = await getValidToken({
+        authJsonPath: options.authJsonPath,
+        env: options.env ?? process.env,
+        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}.`);
+    }
+    const url = buildUrl(path, options.query ?? {});
+    const response = await (options.fetchImpl ?? fetch)(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/json",
+            ...(options.jsonBody === undefined ? {} : { "Content-Type": "application/json" })
+        },
+        body: options.jsonBody === undefined ? undefined : JSON.stringify(options.jsonBody)
+    });
+    const text = await response.text();
+    const body = parseResponseBody(text);
+    if (!response.ok) {
+        const code = typeof body === "object" && body !== null && "error" in body
+            ? JSON.stringify(body.error)
+            : text.slice(0, 500);
+        throw new Error(`Twinkler API request failed: HTTP ${response.status} ${code}`);
+    }
+    return body;
+}
+function normalizeMethod(method) {
+    const normalized = method.trim().toUpperCase();
+    if (!["GET", "POST", "DELETE"].includes(normalized)) {
+        throw new Error("Unsupported method. Use GET, POST, or DELETE.");
+    }
+    return normalized;
+}
+function normalizePath(path) {
+    if (/^https?:\/\//i.test(path)) {
+        throw new Error("Pass only a Twinkler API path, not a full URL.");
+    }
+    const normalized = path.startsWith("/") ? path : `/${path}`;
+    if (!normalized.startsWith("/api/v1/")) {
+        throw new Error("Only Twinkler /api/v1/* paths are allowed.");
+    }
+    if (normalized.includes("..")) {
+        throw new Error("Path traversal is not allowed.");
+    }
+    return normalized;
+}
+function buildUrl(path, query) {
+    const url = new URL(`${DEFAULT_TWINKLER_BASE_URL}${path}`);
+    for (const [key, values] of Object.entries(query)) {
+        for (const value of values)
+            url.searchParams.append(key, value);
+    }
+    return url.toString();
+}
+function parseResponseBody(text) {
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/install/installer.manifest.json

@@ -0,0 +1,11 @@
+{
+  "product": "5mghost-twinkler",
+  "runtime": "node",
+  "packageName": "@mkterswingman/5mghost-twinkler",
+  "binName": "twinkler",
+  "installCommand": "npm install -g @mkterswingman/5mghost-twinkler@latest",
+  "updateCommand": "npm install -g @mkterswingman/5mghost-twinkler@latest",
+  "uninstallCommand": "npm uninstall -g @mkterswingman/5mghost-twinkler",
+  "verifyCommand": "twinkler version",
+  "setupCommand": "twinkler setup"
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mkterswingman/5mghost-twinkler",
+  "version": "0.1.0",
+  "description": "Lightweight AI helper for the 5mghost Twinkler API",
+  "type": "module",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "twinkler": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "skills.manifest.json",
+    "install",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "prepack": "npm run build",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "twinkler",
+    "twitch",
+    "ai",
+    "mkterswingman"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "typescript": "^5.9.3"
+  }
+}

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

@@ -0,0 +1,134 @@
+---
+name: use-5mghost-twinkler
+preamble-tier: 3
+version: 0.1.0
+description: |
+  Use when the user wants Twitch streamer, game, ranking, stream-session, CCV,
+  or chat-watch data from the mkterswingman Twinkler API.
+  Keywords: Twinkler, Twitch, streamer, CCV, chat, watch job, SullyGnome, Arc Raiders.
+---
+
+# Use 5mghost Twinkler
+
+Use the local `twinkler` helper. It adds auth, refreshes short-lived
+mkterswingman access tokens when available, and calls the hosted Twinkler REST
+API. Prefer the helper over hand-written `curl`.
+
+## First Check
+
+Run:
+
+```bash
+twinkler doctor
+```
+
+If the helper is missing, ask the user to install it:
+
+```bash
+npm install -g @mkterswingman/5mghost-twinkler
+twinkler setup
+```
+
+## Auth
+
+Twinkler uses the shared mkterswingman PAT. Do not call it a Twinkler PAT.
+
+If auth is missing:
+
+1. Give the user this URL: <https://mkterswingman.com/pat/login>
+2. Ask the user to copy the mkterswingman PAT.
+3. Start the helper login command and have the user paste the PAT into the
+   helper input, not into the AI chat.
+
+Preferred save path when stdin is available:
+
+```bash
+twinkler auth login --pat-stdin
+```
+
+Then pass the PAT through stdin. Do not put the PAT in command-line arguments
+unless no stdin-capable tool is available.
+
+Fallback:
+
+```bash
+twinkler auth login --pat <TOKEN>
+```
+
+Never echo the PAT back to the user. Never put the PAT in source files, docs,
+logs, URLs, screenshots, PR text, or committed `.env` files. Do not commit
+`~/.mkterswingman/auth.json` or any generated secret/config file to a remote
+repository. Do not ask non-technical users to paste PATs into chat; use the
+helper's stdin path or a secure secret-entry UI.
+
+For AI-managed cloud/server environments, store the PAT as a secret named
+`MKTERSWINGMAN_PAT`. Do not explain environment variables to non-technical
+users unless they ask; configure the target environment yourself when you have
+tool access.
+
+## Preferred Calls
+
+Use:
+
+```bash
+twinkler call GET /api/v1/channel/ibai/summary --query days=30
+twinkler call GET /api/v1/rankings/channels --query sort_by=mostfollowers --query days=30 --query page_size=5
+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` only allows Twinkler `/api/v1/*` paths. It returns JSON on
+stdout.
+
+## Calling The Helper From Scripts
+
+When writing a local automation script for a non-technical user, prefer calling
+the helper instead of re-implementing auth:
+
+```js
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const { stdout } = await execFileAsync("twinkler", [
+  "call",
+  "GET",
+  "/api/v1/channel/ibai/summary",
+  "--query",
+  "days=30",
+]);
+
+const payload = JSON.parse(stdout);
+console.log(payload);
+```
+
+Do not pass PATs as script arguments. Let `twinkler auth login --pat-stdin`
+store the mkterswingman PAT once, then scripts can call `twinkler call`.
+
+## Direct REST Fallback
+
+Use direct REST only when the helper cannot be installed or the runtime is
+non-Node, such as a Python-only cloud job. Direct REST still requires auth.
+
+Python example:
+
+```python
+import os
+import requests
+
+token = os.environ["MKTERSWINGMAN_PAT"]
+
+response = requests.get(
+    "https://mkterswingman.com/5mghost/twinkler/api/v1/channel/ibai/summary",
+    params={"days": "30"},
+    headers={"Authorization": f"Bearer {token}"},
+    timeout=30,
+)
+response.raise_for_status()
+print(response.json())
+```
+
+If `MKTERSWINGMAN_PAT` is missing in a non-helper environment, send the user to
+<https://mkterswingman.com/pat/login>, then store the PAT in the target
+runtime's secret store yourself when tool access provides a safe secret-entry
+mechanism. Do not ask the user to paste the PAT into chat.

package/skills.manifest.json

@@ -0,0 +1,10 @@
+{
+  "product": "5mghost-twinkler",
+  "skills": [
+    {
+      "name": "use-5mghost-twinkler",
+      "source": "skills/use-5mghost-twinkler",
+      "description": "Use the Twinkler helper to call the mkterswingman Twinkler API from AI workflows."
+    }
+  ]
+}