@skillmarkdown/cli 0.1.5 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@
 
 ## Status
 
-Early development. v0 focuses on `skillmd init` and `skillmd validate`. Docs are intentionally lightweight and may evolve.
+Early development. Current command surface includes `skillmd init`, `skillmd validate`, `skillmd login`, and `skillmd logout`. Docs are intentionally lightweight and may evolve.
 
 ## Install
 
@@ -64,9 +64,41 @@ Compare local validation with `skills-ref` (when installed):
 skillmd validate --parity
 ```
 
+### Login with GitHub (Device Flow)
+
+```bash
+skillmd login
+```
+
+By default, `login` uses the project’s built-in development config. You can override values with shell env vars or `~/.skillmd/.env`:
+
+- `SKILLMD_GITHUB_CLIENT_ID`
+- `SKILLMD_FIREBASE_API_KEY`
+
+See `.env.example` for the expected keys.
+Maintainers: built-in defaults are defined in `src/lib/auth-defaults.ts`.
+
+Example override file:
+
+```bash
+mkdir -p ~/.skillmd
+cp .env.example ~/.skillmd/.env
+# then edit values in ~/.skillmd/.env if needed
+```
+
+Session helpers:
+
+```bash
+skillmd login --status
+skillmd login --reauth
+skillmd logout
+```
+
+When a saved session exists, `skillmd login` verifies the stored refresh token. If it is invalid/expired, the CLI automatically starts a new login flow. If verification is inconclusive (for example network timeout), the command exits non-zero and keeps the current session.
+
 ## Development
 
-- Local testing guide: `docs/testing.md`
+- Local testing guide (includes manual `login` auth checks): `docs/testing.md`
 - CI check script: `npm run ci:check`
 - Packed tarball smoke test: `npm run smoke:pack`
 - Optional npm link smoke test: `npm run smoke:link`

package/dist/cli.js

@@ -2,13 +2,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const init_1 = require("./commands/init");
+const login_1 = require("./commands/login");
+const logout_1 = require("./commands/logout");
 const validate_1 = require("./commands/validate");
 const cli_text_1 = require("./lib/cli-text");
 const COMMAND_HANDLERS = {
     init: init_1.runInitCommand,
     validate: validate_1.runValidateCommand,
+    login: login_1.runLoginCommand,
+    logout: logout_1.runLogoutCommand,
 };
-function main() {
+async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
     if (args.length === 0) {
@@ -19,11 +23,11 @@ function main() {
     }
     const handler = COMMAND_HANDLERS[command];
     if (handler) {
-        process.exitCode = handler(args.slice(1));
+        process.exitCode = await handler(args.slice(1));
         return;
     }
     console.error(`skillmd: unknown command '${command}'`);
     console.error(cli_text_1.ROOT_USAGE);
     process.exitCode = 1;
 }
-main();
+void main();

package/dist/commands/login.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLoginCommand = runLoginCommand;
+const cli_text_1 = require("../lib/cli-text");
+const command_output_1 = require("../lib/command-output");
+const auth_config_1 = require("../lib/auth-config");
+const auth_session_1 = require("../lib/auth-session");
+const github_device_flow_1 = require("../lib/github-device-flow");
+const firebase_auth_1 = require("../lib/firebase-auth");
+function parseFlags(args) {
+    let status = false;
+    let reauth = false;
+    for (const arg of args) {
+        if (arg === "--status") {
+            status = true;
+            continue;
+        }
+        if (arg === "--reauth") {
+            reauth = true;
+            continue;
+        }
+        return { status: false, reauth: false, valid: false };
+    }
+    if (status && reauth) {
+        return { status: false, reauth: false, valid: false };
+    }
+    return { status, reauth, valid: true };
+}
+function printSessionStatus(session) {
+    if (!session) {
+        console.log("Not logged in.");
+        return 1;
+    }
+    if (session.email) {
+        console.log(`Logged in with GitHub as ${session.email}.`);
+        return 0;
+    }
+    console.log(`Logged in with GitHub (uid: ${session.uid}).`);
+    return 0;
+}
+function requireConfig(env) {
+    try {
+        return (0, auth_config_1.getLoginEnvConfig)(env);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "invalid login configuration";
+        const wrapped = new Error(`${message}.`);
+        wrapped.cause = error;
+        throw wrapped;
+    }
+}
+async function runLoginCommand(args, options = {}) {
+    const { status, reauth, valid } = parseFlags(args);
+    if (!valid) {
+        return (0, command_output_1.failWithUsage)("skillmd login: unsupported argument(s)", cli_text_1.LOGIN_USAGE);
+    }
+    const readSessionFn = options.readSession ?? auth_session_1.readAuthSession;
+    const writeSessionFn = options.writeSession ?? auth_session_1.writeAuthSession;
+    const clearSessionFn = options.clearSession ?? auth_session_1.clearAuthSession;
+    if (status) {
+        return printSessionStatus(readSessionFn());
+    }
+    try {
+        const config = requireConfig(options.env ?? process.env);
+        const existingSession = readSessionFn();
+        if (existingSession && !reauth) {
+            const verifyRefreshTokenFn = options.verifyRefreshToken ?? firebase_auth_1.verifyFirebaseRefreshToken;
+            try {
+                const validation = await verifyRefreshTokenFn(config.firebaseApiKey, existingSession.refreshToken);
+                if (validation.valid) {
+                    if (existingSession.email) {
+                        console.log(`Already logged in as ${existingSession.email}. Run 'skillmd logout' first.`);
+                    }
+                    else {
+                        console.log("Already logged in. Run 'skillmd logout' first.");
+                    }
+                    return 0;
+                }
+                clearSessionFn();
+                console.log("Existing session is no longer valid. Starting re-authentication.");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Unknown error";
+                console.error(`skillmd login: unable to verify existing session (${message}). ` +
+                    "Keeping current session. Run 'skillmd login --reauth' to force reauthentication.");
+                return 1;
+            }
+        }
+        const requestDeviceCodeFn = options.requestDeviceCode ?? github_device_flow_1.requestDeviceCode;
+        const pollForAccessTokenFn = options.pollForAccessToken ?? github_device_flow_1.pollForAccessToken;
+        const signInFn = options.signInWithGitHubAccessToken ?? firebase_auth_1.signInWithGitHubAccessToken;
+        const deviceCode = await requestDeviceCodeFn(config.githubClientId);
+        console.log("Open this URL in your browser to authorize skillmd:");
+        console.log(deviceCode.verificationUriComplete ?? deviceCode.verificationUri);
+        console.log(`Then enter code: ${deviceCode.userCode}`);
+        const token = await pollForAccessTokenFn(config.githubClientId, deviceCode.deviceCode, deviceCode.interval, deviceCode.expiresIn);
+        const firebaseSession = await signInFn(config.firebaseApiKey, token.accessToken);
+        writeSessionFn({
+            provider: "github",
+            uid: firebaseSession.localId,
+            email: firebaseSession.email,
+            refreshToken: firebaseSession.refreshToken,
+        });
+        if (firebaseSession.email) {
+            console.log(`Login successful. Signed in as ${firebaseSession.email}.`);
+        }
+        else {
+            console.log("Login successful.");
+        }
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        console.error(`skillmd login: ${message}`);
+        return 1;
+    }
+}

package/dist/commands/logout.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLogoutCommand = runLogoutCommand;
+const cli_text_1 = require("../lib/cli-text");
+const command_output_1 = require("../lib/command-output");
+const auth_session_1 = require("../lib/auth-session");
+function runLogoutCommand(args, options = {}) {
+    if (args.length > 0) {
+        return (0, command_output_1.failWithUsage)("skillmd logout: unsupported argument(s)", cli_text_1.LOGOUT_USAGE);
+    }
+    const clearSessionFn = options.clearSession ?? auth_session_1.clearAuthSession;
+    const removed = clearSessionFn();
+    if (removed) {
+        console.log("Logged out.");
+        return 0;
+    }
+    console.log("No active session to log out.");
+    return 0;
+}

package/dist/lib/auth-config.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLoginEnvConfig = getLoginEnvConfig;
+exports.getDefaultUserEnvPath = getDefaultUserEnvPath;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const auth_defaults_1 = require("./auth-defaults");
+const USER_ENV_RELATIVE_PATH = ".skillmd/.env";
+function parseDotEnv(content) {
+    const values = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const equalIndex = line.indexOf("=");
+        if (equalIndex <= 0) {
+            continue;
+        }
+        const key = line.slice(0, equalIndex).trim();
+        if (!key) {
+            continue;
+        }
+        let value = line.slice(equalIndex + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        values[key] = value;
+    }
+    return values;
+}
+function loadDotEnv(dotEnvPath) {
+    if (!(0, node_fs_1.existsSync)(dotEnvPath)) {
+        return {};
+    }
+    try {
+        return parseDotEnv((0, node_fs_1.readFileSync)(dotEnvPath, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function pickValue(...candidates) {
+    for (const candidate of candidates) {
+        if (candidate && candidate.trim()) {
+            return candidate.trim();
+        }
+    }
+    return undefined;
+}
+function getLoginEnvConfig(env = process.env, options = {}) {
+    const dotEnv = loadDotEnv(getDefaultUserEnvPath(options));
+    const githubClientId = pickValue(env.SKILLMD_GITHUB_CLIENT_ID, dotEnv.SKILLMD_GITHUB_CLIENT_ID, auth_defaults_1.DEFAULT_LOGIN_AUTH_CONFIG.githubClientId);
+    const firebaseApiKey = pickValue(env.SKILLMD_FIREBASE_API_KEY, dotEnv.SKILLMD_FIREBASE_API_KEY, auth_defaults_1.DEFAULT_LOGIN_AUTH_CONFIG.firebaseApiKey);
+    if (!githubClientId || !firebaseApiKey) {
+        throw new Error("missing login configuration");
+    }
+    return {
+        githubClientId,
+        firebaseApiKey,
+    };
+}
+function getDefaultUserEnvPath(options = {}) {
+    return (0, node_path_1.join)(options.homeDir ?? (0, node_os_1.homedir)(), USER_ENV_RELATIVE_PATH);
+}

package/dist/lib/auth-defaults.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LOGIN_AUTH_CONFIG = void 0;
+// Single source of truth for built-in auth defaults.
+exports.DEFAULT_LOGIN_AUTH_CONFIG = Object.freeze({
+    githubClientId: "Ov23lixkdtyLp35IFaBG",
+    firebaseApiKey: "AIzaSyAkaZRmpCvZasFjeRAfW_b0V0nUcGOTjok",
+});

package/dist/lib/auth-session.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultSessionPath = getDefaultSessionPath;
+exports.readAuthSession = readAuthSession;
+exports.writeAuthSession = writeAuthSession;
+exports.clearAuthSession = clearAuthSession;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const SESSION_PATH = (0, node_path_1.join)((0, node_os_1.homedir)(), ".skillmd", "auth.json");
+function getDefaultSessionPath() {
+    return SESSION_PATH;
+}
+function readAuthSession(sessionPath = SESSION_PATH) {
+    if (!(0, node_fs_1.existsSync)(sessionPath)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(sessionPath, "utf8"));
+        if (!parsed ||
+            parsed.provider !== "github" ||
+            typeof parsed.uid !== "string" ||
+            parsed.uid.length === 0 ||
+            typeof parsed.refreshToken !== "string" ||
+            parsed.refreshToken.length === 0) {
+            return null;
+        }
+        if (parsed.email !== undefined && typeof parsed.email !== "string") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeAuthSession(session, sessionPath = SESSION_PATH) {
+    const parentDir = (0, node_path_1.dirname)(sessionPath);
+    (0, node_fs_1.mkdirSync)(parentDir, { recursive: true });
+    (0, node_fs_1.writeFileSync)(sessionPath, JSON.stringify(session, null, 2), { encoding: "utf8", mode: 0o600 });
+    (0, node_fs_1.chmodSync)(sessionPath, 0o600);
+}
+function clearAuthSession(sessionPath = SESSION_PATH) {
+    if (!(0, node_fs_1.existsSync)(sessionPath)) {
+        return false;
+    }
+    (0, node_fs_1.rmSync)(sessionPath, { force: true });
+    return true;
+}

package/dist/lib/cli-text.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VALIDATE_USAGE = exports.INIT_USAGE = exports.ROOT_USAGE = void 0;
-exports.ROOT_USAGE = "Usage: skillmd <init|validate>";
+exports.LOGOUT_USAGE = exports.LOGIN_USAGE = exports.VALIDATE_USAGE = exports.INIT_USAGE = exports.ROOT_USAGE = void 0;
+exports.ROOT_USAGE = "Usage: skillmd <init|validate|login|logout>";
 exports.INIT_USAGE = "Usage: skillmd init [--no-validate]";
 exports.VALIDATE_USAGE = "Usage: skillmd validate [path] [--strict] [--parity]";
+exports.LOGIN_USAGE = "Usage: skillmd login [--status|--reauth]";
+exports.LOGOUT_USAGE = "Usage: skillmd logout";

package/dist/lib/firebase-auth.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signInWithGitHubAccessToken = signInWithGitHubAccessToken;
+exports.verifyFirebaseRefreshToken = verifyFirebaseRefreshToken;
+const http_1 = require("./http");
+const FIREBASE_HTTP_TIMEOUT_MS = 10000;
+async function parseJsonApiResponse(response, apiLabel) {
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${apiLabel} returned non-JSON response (${response.status})`);
+    }
+}
+async function signInWithGitHubAccessToken(apiKey, githubAccessToken) {
+    const response = await (0, http_1.fetchWithTimeout)(`https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=${encodeURIComponent(apiKey)}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            requestUri: "http://localhost",
+            returnSecureToken: true,
+            returnIdpCredential: true,
+            postBody: `access_token=${encodeURIComponent(githubAccessToken)}&providerId=github.com`,
+        }),
+    }, { timeoutMs: FIREBASE_HTTP_TIMEOUT_MS });
+    const payload = await parseJsonApiResponse(response, "Firebase auth API");
+    if (!response.ok) {
+        const message = payload.error?.message || "Firebase signInWithIdp request failed";
+        throw new Error(`Firebase auth error: ${message}`);
+    }
+    if (!payload.localId || !payload.refreshToken) {
+        throw new Error("Firebase auth response was missing required fields");
+    }
+    return {
+        localId: payload.localId,
+        email: payload.email,
+        refreshToken: payload.refreshToken,
+    };
+}
+async function verifyFirebaseRefreshToken(apiKey, refreshToken) {
+    const response = await (0, http_1.fetchWithTimeout)(`https://securetoken.googleapis.com/v1/token?key=${encodeURIComponent(apiKey)}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+        }),
+    }, { timeoutMs: FIREBASE_HTTP_TIMEOUT_MS });
+    const payload = await parseJsonApiResponse(response, "Firebase token API");
+    if (response.ok) {
+        if (!payload.refresh_token || !payload.access_token) {
+            throw new Error("Firebase token API response was missing required fields");
+        }
+        return { valid: true };
+    }
+    const errorMessage = payload.error?.message ?? "";
+    if (response.status === 400 &&
+        (errorMessage === "INVALID_REFRESH_TOKEN" || errorMessage === "TOKEN_EXPIRED")) {
+        return { valid: false };
+    }
+    throw new Error(`Firebase token verification failed (${response.status}): ${errorMessage || "unknown error"}`);
+}

package/dist/lib/github-device-flow.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestDeviceCode = requestDeviceCode;
+exports.pollForAccessToken = pollForAccessToken;
+const http_1 = require("./http");
+const GITHUB_DEVICE_CODE_URL = "https://github.com/login/device/code";
+const GITHUB_ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token";
+const GITHUB_HTTP_TIMEOUT_MS = 10000;
+async function postGitHubForm(url, form) {
+    const response = await (0, http_1.fetchWithTimeout)(url, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: form,
+    }, { timeoutMs: GITHUB_HTTP_TIMEOUT_MS });
+    const text = await response.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`GitHub API returned non-JSON response (${response.status})`);
+    }
+    if (!response.ok) {
+        throw new Error(`GitHub API request failed (${response.status})`);
+    }
+    return parsed;
+}
+async function requestDeviceCode(clientId, scope = "read:user user:email") {
+    const payload = await postGitHubForm(GITHUB_DEVICE_CODE_URL, new URLSearchParams({
+        client_id: clientId,
+        scope,
+    }));
+    if (!payload.device_code ||
+        !payload.user_code ||
+        !payload.verification_uri ||
+        !payload.expires_in) {
+        throw new Error("GitHub device code response was missing required fields");
+    }
+    return {
+        deviceCode: payload.device_code,
+        userCode: payload.user_code,
+        verificationUri: payload.verification_uri,
+        verificationUriComplete: payload.verification_uri_complete,
+        expiresIn: payload.expires_in,
+        interval: payload.interval ?? 5,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function pollForAccessToken(clientId, deviceCode, intervalSeconds, expiresInSeconds, options = {}) {
+    const startedAt = Date.now();
+    let pollInterval = Math.max(1, intervalSeconds);
+    const sleepFn = options.sleep ?? sleep;
+    while (Date.now() - startedAt < expiresInSeconds * 1000) {
+        await sleepFn(pollInterval * 1000);
+        const payload = await postGitHubForm(GITHUB_ACCESS_TOKEN_URL, new URLSearchParams({
+            client_id: clientId,
+            device_code: deviceCode,
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        }));
+        if (payload.access_token) {
+            return { accessToken: payload.access_token };
+        }
+        if (!payload.error || payload.error === "authorization_pending") {
+            continue;
+        }
+        if (payload.error === "slow_down") {
+            pollInterval += 5;
+            continue;
+        }
+        if (payload.error === "expired_token") {
+            throw new Error("GitHub device code expired before authorization completed");
+        }
+        if (payload.error === "access_denied") {
+            throw new Error("GitHub authorization was denied by the user");
+        }
+        throw new Error(payload.error_description || `GitHub OAuth error: ${payload.error}`);
+    }
+    throw new Error("GitHub device login timed out");
+}

package/dist/lib/http.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchWithTimeout = fetchWithTimeout;
+const DEFAULT_TIMEOUT_MS = 10000;
+async function fetchWithTimeout(input, init = {}, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const userSignal = init.signal;
+    let abortListener;
+    if (userSignal) {
+        if (userSignal.aborted) {
+            controller.abort(userSignal.reason);
+        }
+        else {
+            abortListener = () => {
+                controller.abort(userSignal.reason);
+            };
+            userSignal.addEventListener("abort", abortListener, { once: true });
+        }
+    }
+    const timeout = setTimeout(() => {
+        controller.abort(new Error(`request timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    try {
+        return await fetch(input, {
+            ...init,
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError" && !userSignal?.aborted) {
+            const timeoutError = new Error(`request timed out after ${timeoutMs}ms`);
+            timeoutError.cause = error;
+            throw timeoutError;
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+        if (userSignal && abortListener) {
+            userSignal.removeEventListener("abort", abortListener);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillmarkdown/cli",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "CLI for scaffolding SKILL.md-based AI skills",
   "license": "MIT",
   "type": "commonjs",