@mkterswingman/5mghost-twinkler 0.1.0 → 0.1.3

package/README.md

@@ -4,10 +4,13 @@ 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
 ```
 
+`npm install -g` installs bundled AI skills automatically for detected AI
+clients. `twinkler setup` remains an idempotent repair command when a skill
+target was unavailable during install.
+
 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/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
+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";
@@ -17,6 +18,7 @@ const HELP = [
     "  twinkler auth login --pat <TOKEN>",
     "  twinkler auth login --pat-stdin",
     "  twinkler call <GET|POST|DELETE> /api/v1/... [--query k=v] [--json '{...}']",
+    "  twinkler update",
     "  twinkler version",
     "",
     "mkterswingman PAT:",
@@ -72,6 +74,9 @@ export async function runCli(context = {}) {
                 ].join("\n"));
                 return results.some((result) => result.status === "error") ? 1 : 0;
             }
+            case "update":
+            case "upgrade":
+                return runUpdateCommand(args, { env, out, err });
             case "doctor": {
                 const auth = getAuthStatus({ authJsonPath: paths.authJsonPath, env });
                 out([
@@ -188,6 +193,30 @@ function renderSkillInstallResults(results) {
         })
     ].join("\n");
 }
+function runUpdateCommand(args, context) {
+    const dryRun = args.includes("--dry-run") || context.env.TWINKLER_UPDATE_DRY_RUN === "1";
+    const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+    const installArgs = ["install", "-g", "@mkterswingman/5mghost-twinkler@latest"];
+    if (dryRun) {
+        context.out(`Update command: ${npmCommand} ${installArgs.join(" ")}`);
+        return 0;
+    }
+    context.out("Updating Twinkler helper...");
+    const result = spawnSync(npmCommand, installArgs, {
+        stdio: "inherit",
+        env: context.env
+    });
+    if (result.error) {
+        context.err(`Update failed: ${result.error.message}`);
+        return 1;
+    }
+    if (result.status !== 0) {
+        context.err(`Update failed: npm exited with ${result.status ?? "unknown status"}`);
+        return result.status ?? 1;
+    }
+    context.out("Twinkler updated. Restart your AI session so newly installed skill text is loaded.");
+    return 0;
+}
 async function readAllStdin(stdin) {
     const chunks = [];
     for await (const chunk of stdin) {
@@ -208,7 +237,17 @@ function readPackageVersion() {
     }
     return "0.0.0";
 }
-if (import.meta.url === `file://${process.argv[1]}`) {
+function isDirectCliEntrypoint() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return import.meta.url === `file://${process.argv[1]}`;
+    }
+}
+if (isDirectCliEntrypoint()) {
     runCli().then((code) => {
         process.exitCode = code;
     });

package/dist/skillInstall.d.ts

@@ -1,5 +1,7 @@
 export interface InstallSkillsOptions {
-    homeDir: string;
+    homeDir?: string;
+    detectedAgents?: string[];
+    repairTargets?: boolean;
 }
 export interface SkillInstallResult {
     agent: string;
@@ -7,5 +9,6 @@ export interface SkillInstallResult {
     status: "installed" | "skipped" | "error";
     targetDir: string;
     reason?: string;
+    contentHash?: string;
 }
-export declare function installBundledSkills(options: InstallSkillsOptions): SkillInstallResult[];
+export declare function installBundledSkills(options?: InstallSkillsOptions): SkillInstallResult[];

package/dist/skillInstall.js

@@ -1,58 +1,86 @@
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { applyAgentOverrides, getTargetDir, installSkills, listDetectedAgents, loadBuiltInRegistry, RECEIPT_FILENAME } from "@mkterswingman/5mghost-agent-skills";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
 import { resolveBundledAssetPath } from "./paths.js";
-const TARGETS = [
-    { agent: "codex", skillsDir: ".codex/skills" },
-    { agent: "agents", skillsDir: ".agents/skills" }
+const AGENT_OVERRIDES = {
+    agents: {
+        label: "Agents legacy skills",
+        detect: { kind: "path", path: "~/.agents" },
+        skillsDir: "~/.agents/skills",
+        installMethod: "copy"
+    }
+};
+const TWINKLER_SKILLS = [
+    "setup-5mghost-twinkler",
+    "use-5mghost-twinkler",
+    "update-5mghost-twinkler"
 ];
-export function installBundledSkills(options) {
+const LEGACY_RECEIPT_FILENAME = ".install-receipt.json";
+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);
+    const detectedAgents = options.detectedAgents ??
+        listDetectedAgents({
+            homeDir: options.homeDir,
+            agentOverrides: AGENT_OVERRIDES
+        });
+    const setupTargets = options.repairTargets === false
+        ? detectedAgents
+        : Array.from(new Set([...detectedAgents, "codex", "agents"]));
+    removeLegacyOwnedTargets(options.homeDir, setupTargets);
+    return normalizeSummary(installSkills({
+        manifestPath,
+        homeDir: options.homeDir,
+        agentOverrides: AGENT_OVERRIDES,
+        detectedAgents: setupTargets
+    }));
+}
+function removeLegacyOwnedTargets(homeDir, agentNames) {
+    const registry = applyAgentOverrides(loadBuiltInRegistry(), AGENT_OVERRIDES);
+    for (const agentName of agentNames) {
+        const agent = registry.agents[agentName];
+        if (!agent)
+            continue;
+        for (const skillName of TWINKLER_SKILLS) {
+            const targetDir = getTargetDir(homeDir, agent.skillsDir, skillName);
+            const receiptPath = findReceiptPath(targetDir);
+            if (!existsSync(receiptPath))
+                continue;
+            let receipt;
             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
-                });
+                receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
             }
-            catch (error) {
-                results.push({
-                    agent: target.agent,
-                    skill: skill.name,
-                    status: "error",
-                    targetDir,
-                    reason: error instanceof Error ? error.message : String(error)
-                });
+            catch {
+                continue;
+            }
+            if (receipt.installedBy === undefined &&
+                receipt.product === "5mghost-twinkler" &&
+                receipt.skill === skillName &&
+                receipt.agent === agentName) {
+                rmSync(targetDir, { recursive: true, force: true });
             }
         }
     }
-    return results;
+}
+function findReceiptPath(targetDir) {
+    const current = join(targetDir, RECEIPT_FILENAME);
+    if (existsSync(current))
+        return current;
+    return join(targetDir, LEGACY_RECEIPT_FILENAME);
+}
+function normalizeSummary(summary) {
+    return summary.results.map((result) => {
+        const status = result.status === "installed" || result.status === "updated"
+            ? "installed"
+            : result.status === "error"
+                ? "error"
+                : "skipped";
+        return {
+            agent: result.agent,
+            skill: result.skill,
+            status,
+            targetDir: result.targetDir,
+            reason: result.reason,
+            contentHash: result.contentHash
+        };
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/5mghost-twinkler",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Lightweight AI helper for the 5mghost Twinkler API",
   "type": "module",
   "engines": {
@@ -9,8 +9,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/5mghost/mcp_projects.git",
+    "directory": "5mghost-twinkler/client"
+  },
   "bin": {
-    "twinkler": "./dist/cli.js"
+    "twinkler": "dist/cli.js"
   },
   "exports": {
     ".": {
@@ -23,13 +28,15 @@
     "skills",
     "skills.manifest.json",
     "install",
+    "scripts",
     "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"
+    "pack:dry": "npm pack --dry-run",
+    "postinstall": "node scripts/postinstall.mjs"
   },
   "keywords": [
     "twinkler",
@@ -37,6 +44,9 @@
     "ai",
     "mkterswingman"
   ],
+  "dependencies": {
+    "@mkterswingman/5mghost-agent-skills": "^0.0.1"
+  },
   "devDependencies": {
     "@types/node": "^25.3.2",
     "typescript": "^5.9.3"

package/scripts/postinstall.mjs

@@ -0,0 +1,51 @@
+// Runs after `npm install -g` to install Twinkler skills into detected AI clients.
+// This script is intentionally non-fatal: npm install must still succeed when
+// an AI client is not installed or a skill target is locked down.
+
+const agentOverrides = {
+  agents: {
+    label: "Agents legacy skills",
+    detect: { kind: "path", path: "~/.agents" },
+    skillsDir: "~/.agents/skills",
+    installMethod: "copy"
+  }
+};
+
+let listDetectedAgents;
+let installBundledSkills;
+
+try {
+  ({ listDetectedAgents } = await import("@mkterswingman/5mghost-agent-skills"));
+  ({ installBundledSkills } = await import("../dist/skillInstall.js"));
+} catch (error) {
+  console.log("[twinkler] agent-skills not available; skipping skill install.");
+  process.exit(0);
+}
+
+let agents;
+try {
+  agents = listDetectedAgents({ agentOverrides });
+} catch (error) {
+  console.log("[twinkler] Could not detect AI clients; skipping skill install.");
+  process.exit(0);
+}
+
+if (!agents || agents.length === 0) {
+  console.log("[twinkler] No AI clients detected; skipping skill install.");
+  process.exit(0);
+}
+
+try {
+  const results = installBundledSkills({ detectedAgents: agents, repairTargets: false });
+  const installed = results
+    .filter((entry) => entry.status === "installed")
+    .map((entry) => `${entry.agent}:${entry.skill}`);
+  if (installed.length > 0) {
+    console.log(`[twinkler] Installed skills: ${installed.join(", ")}`);
+    console.log("[twinkler] Restart your AI session before invoking the new skill text.");
+  } else {
+    console.log("[twinkler] No skill targets updated.");
+  }
+} catch (error) {
+  console.log(`[twinkler] Skill install failed (non-fatal): ${String(error)}`);
+}

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

@@ -0,0 +1,71 @@
+---
+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/update-5mghost-twinkler/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: update-5mghost-twinkler
+preamble-tier: 3
+version: 0.2.0
+description: |
+  Update the Twinkler helper package and refresh bundled AI skills.
+---
+
+# Update 5mghost Twinkler
+
+Use when the user asks to update, upgrade, repair stale skills, or pick up a new
+Twinkler helper release.
+
+## Default Path
+
+Run:
+
+```bash
+twinkler update
+```
+
+This runs the npm global update for `@mkterswingman/5mghost-twinkler@latest`.
+The package postinstall refreshes bundled skills automatically.
+
+If `twinkler update` is unavailable because the installed version is old, run:
+
+```bash
+npm install -g @mkterswingman/5mghost-twinkler@latest
+twinkler setup
+```
+
+Then ask the user to restart the AI session so updated skill text is loaded.
+
+## Verify
+
+```bash
+twinkler version
+twinkler doctor
+```
+
+Do not ask the user to edit skill directories or hidden config files manually.

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

@@ -1,7 +1,7 @@
 ---
 name: use-5mghost-twinkler
 preamble-tier: 3
-version: 0.1.0
+version: 0.2.0
 description: |
   Use when the user wants Twitch streamer, game, ranking, stream-session, CCV,
   or chat-watch data from the mkterswingman Twinkler API.
@@ -10,7 +10,7 @@ description: |
 
 # Use 5mghost Twinkler
 
-Use the local `twinkler` helper. It adds auth, refreshes short-lived
+Use the local `twinkler` helper. It handles auth, refreshes short-lived
 mkterswingman access tokens when available, and calls the hosted Twinkler REST
 API. Prefer the helper over hand-written `curl`.
 
@@ -22,62 +22,67 @@ Run:
 twinkler doctor
 ```
 
-If the helper is missing, ask the user to install it:
-
-```bash
-npm install -g @mkterswingman/5mghost-twinkler
-twinkler setup
-```
+If the helper is missing or auth is missing, use `setup-5mghost-twinkler`.
+Do not ask non-technical users to understand CLI concepts; operate the helper
+for them and explain only the action they need to take.
 
 ## Auth
 
-Twinkler uses the shared mkterswingman PAT. Do not call it a Twinkler PAT.
+Twinkler uses the shared mkterswingman login/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.
+3. Start `twinkler auth login --pat-stdin`.
+4. Have the user paste the PAT into that local input, not into AI chat.
+
+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.
+
+## Common Calls
 
-Preferred save path when stdin is available:
+Use:
 
 ```bash
-twinkler auth login --pat-stdin
+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
 ```
 
-Then pass the PAT through stdin. Do not put the PAT in command-line arguments
-unless no stdin-capable tool is available.
+`twinkler call` only allows Twinkler `/api/v1/*` paths. It returns JSON on
+stdout.
+
+## Watch Jobs
+
+Use watch jobs when the user asks to monitor a currently live Twitch channel,
+collect CCV points, collect chat messages, or stop when the stream ends or
+changes game.
 
-Fallback:
+Create:
 
 ```bash
-twinkler auth login --pat <TOKEN>
+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"}}'
 ```
 
-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.
+The response contains a `job_id`. Save it in your working notes. Then poll:
 
-## Preferred Calls
+```bash
+twinkler call GET /api/v1/twitch/watch/<job_id>
+twinkler call GET /api/v1/twitch/watch/<job_id>/ccv
+twinkler call GET /api/v1/twitch/watch/<job_id>/chat
+```
 
-Use:
+Stop/cleanup when the user is done:
 
 ```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 DELETE /api/v1/twitch/watch/<job_id>
 ```
 
-`twinkler call` only allows Twinkler `/api/v1/*` paths. It returns JSON on
-stdout.
+Normal logged-in users can create and delete their own watch jobs. If the API
+returns `WATCH_DISABLED`, explain that the hosted watch worker is not enabled
+right now. If it returns `AUTH_*`, repair mkterswingman auth. If it returns a
+limit error, tell the user which limit was hit and stop creating more jobs.
 
 ## Calling The Helper From Scripts
 
@@ -110,8 +115,6 @@ store the mkterswingman PAT once, then scripts can call `twinkler call`.
 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

package/skills.manifest.json

@@ -1,10 +1,54 @@
 {
+  "schemaVersion": 1,
   "product": "5mghost-twinkler",
   "skills": [
+    {
+      "name": "setup-5mghost-twinkler",
+      "source": { "type": "local", "path": "./skills/setup-5mghost-twinkler" },
+      "targets": [
+        "claude",
+        "claude-internal",
+        "codex",
+        "codex-internal",
+        "gemini",
+        "gemini-internal",
+        "openclaw",
+        "workbuddy",
+        "codebuddy",
+        "agents"
+      ]
+    },
     {
       "name": "use-5mghost-twinkler",
-      "source": "skills/use-5mghost-twinkler",
-      "description": "Use the Twinkler helper to call the mkterswingman Twinkler API from AI workflows."
+      "source": { "type": "local", "path": "./skills/use-5mghost-twinkler" },
+      "targets": [
+        "claude",
+        "claude-internal",
+        "codex",
+        "codex-internal",
+        "gemini",
+        "gemini-internal",
+        "openclaw",
+        "workbuddy",
+        "codebuddy",
+        "agents"
+      ]
+    },
+    {
+      "name": "update-5mghost-twinkler",
+      "source": { "type": "local", "path": "./skills/update-5mghost-twinkler" },
+      "targets": [
+        "claude",
+        "claude-internal",
+        "codex",
+        "codex-internal",
+        "gemini",
+        "gemini-internal",
+        "openclaw",
+        "workbuddy",
+        "codebuddy",
+        "agents"
+      ]
     }
   ]
 }