@skillmarkdown/cli 0.2.1 → 0.3.0

package/README.md

@@ -28,7 +28,31 @@ npx @skillmarkdown/cli init
 skillmd init
 ```
 
-This scaffolds a spec-aligned skill structure including `SKILL.md` and optional directories (`scripts/`, `references/`, `assets/`), then runs local validation.
+Default `init` creates the minimal filesystem scaffold:
+
+- `SKILL.md` only
+
+and runs spec validation.
+
+To scaffold the full verbose template:
+
+```bash
+skillmd init --template verbose
+```
+
+The `verbose` template includes `SKILL.md`, `.gitignore`, and optional directories (`scripts/`, `references/`, `assets/`) with starter placeholder content and `.gitkeep`, then runs strict validation.
+
+Included starter files:
+
+- `scripts/README.md`
+- `scripts/extract.py`
+- `references/REFERENCE.md`
+- `references/FORMS.md`
+- `assets/README.md`
+- `assets/report-template.md`
+- `assets/lookup-table.csv`
+
+`SKILL.md` content is the same across `minimal` and `verbose` templates. Template selection only changes extra scaffold files/directories around `SKILL.md`.
 
 To skip validation during init:
 
@@ -36,6 +60,11 @@ To skip validation during init:
 skillmd init --no-validate
 ```
 
+Supported templates:
+
+- `minimal` (default)
+- `verbose`
+
 ### Validate a skill folder
 
 ```bash
@@ -77,7 +106,7 @@ By default, `login` uses the project’s built-in development config. You can ov
 - `SKILLMD_FIREBASE_PROJECT_ID`
 
 See `.env.example` for the expected keys.
-Maintainers: built-in defaults are defined in `src/lib/auth-defaults.ts`.
+Maintainers: built-in defaults are defined in `src/lib/auth/defaults.ts`.
 
 Example override file:
 

package/dist/cli.js

@@ -5,7 +5,7 @@ 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 cli_text_1 = require("./lib/shared/cli-text");
 const COMMAND_HANDLERS = {
     init: init_1.runInitCommand,
     validate: validate_1.runValidateCommand,
@@ -30,4 +30,8 @@ async function main() {
     console.error(cli_text_1.ROOT_USAGE);
     process.exitCode = 1;
 }
-void main();
+void main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    console.error(`skillmd: ${message}`);
+    process.exitCode = 1;
+});

package/dist/commands/init.js

@@ -1,26 +1,57 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runInitCommand = runInitCommand;
-const cli_text_1 = require("../lib/cli-text");
-const command_output_1 = require("../lib/command-output");
-const scaffold_1 = require("../lib/scaffold");
-const validator_1 = require("../lib/validator");
+const cli_text_1 = require("../lib/shared/cli-text");
+const command_output_1 = require("../lib/shared/command-output");
+const scaffold_1 = require("../lib/scaffold/scaffold");
+const validator_1 = require("../lib/validation/validator");
+function parseInitArgs(args) {
+    let skipValidation = false;
+    let template = "minimal";
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--no-validate") {
+            skipValidation = true;
+            continue;
+        }
+        if (arg === "--template") {
+            const nextValue = args[index + 1];
+            const resolved = nextValue ? (0, scaffold_1.resolveInitTemplateId)(nextValue) : null;
+            if (!resolved) {
+                return { skipValidation: false, template: "minimal", valid: false };
+            }
+            template = resolved;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--template=")) {
+            const value = arg.slice("--template=".length);
+            const resolved = (0, scaffold_1.resolveInitTemplateId)(value);
+            if (!resolved) {
+                return { skipValidation: false, template: "minimal", valid: false };
+            }
+            template = resolved;
+            continue;
+        }
+        return { skipValidation: false, template: "minimal", valid: false };
+    }
+    return { skipValidation, template, valid: true };
+}
 function runInitCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
-    const validateSkillFn = options.validateSkill ?? ((targetDir) => (0, validator_1.validateSkill)(targetDir, { strict: true }));
-    const skipValidation = args.includes("--no-validate");
-    const hasUnsupportedArgs = args.length > 1 || (args.length === 1 && args[0] !== "--no-validate");
-    if (hasUnsupportedArgs) {
+    const validateSkillFn = options.validateSkill ?? validator_1.validateSkill;
+    const { skipValidation, template, valid } = parseInitArgs(args);
+    if (!valid) {
         return (0, command_output_1.failWithUsage)("skillmd init: unsupported argument(s)", cli_text_1.INIT_USAGE);
     }
     try {
-        const result = (0, scaffold_1.scaffoldSkillInDirectory)(cwd);
+        const result = (0, scaffold_1.scaffoldSkillInDirectory)(cwd, { template });
         console.log(`Initialized skill '${result.skillName}'.`);
         if (skipValidation) {
             console.log("Validation skipped (--no-validate).");
             return 0;
         }
-        const validation = validateSkillFn(cwd);
+        const validation = validateSkillFn(cwd, { strict: result.template === "verbose" });
         (0, command_output_1.printValidationResult)(validation);
         if (validation.status === "passed") {
             return 0;

package/dist/commands/login.js

@@ -1,64 +1,18 @@
 "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 formatSessionProject(session, currentConfigProjectId) {
-    if (!session.projectId) {
-        if (currentConfigProjectId) {
-            return { label: `unknown (current config: ${currentConfigProjectId})`, mismatch: false };
-        }
-        return { label: "unknown", mismatch: false };
-    }
-    return {
-        label: session.projectId,
-        mismatch: Boolean(currentConfigProjectId && session.projectId !== currentConfigProjectId),
-    };
-}
-function printSessionStatus(session, currentConfigProjectId) {
-    if (!session) {
-        console.log("Not logged in.");
-        return 1;
-    }
-    const project = formatSessionProject(session, currentConfigProjectId);
-    if (session.email) {
-        console.log(`Logged in with GitHub as ${session.email} (project: ${project.label}).`);
-    }
-    else {
-        console.log(`Logged in with GitHub (uid: ${session.uid}, project: ${project.label}).`);
-    }
-    if (project.mismatch && currentConfigProjectId) {
-        console.log(`Current CLI config targets project '${currentConfigProjectId}'. ` +
-            "Run 'skillmd login --reauth' to switch projects.");
-    }
-    return 0;
-}
+const cli_text_1 = require("../lib/shared/cli-text");
+const command_output_1 = require("../lib/shared/command-output");
+const config_1 = require("../lib/auth/config");
+const session_1 = require("../lib/auth/session");
+const github_device_flow_1 = require("../lib/auth/github-device-flow");
+const firebase_auth_1 = require("../lib/auth/firebase-auth");
+const login_flow_1 = require("../lib/auth/login-flow");
+const login_flags_1 = require("../lib/auth/login-flags");
+const login_status_1 = require("../lib/auth/login-status");
 function requireConfig(env) {
     try {
-        return (0, auth_config_1.getLoginEnvConfig)(env);
+        return (0, config_1.getLoginEnvConfig)(env);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "invalid login configuration";
@@ -68,72 +22,27 @@ function requireConfig(env) {
     }
 }
 async function runLoginCommand(args, options = {}) {
-    const { status, reauth, valid } = parseFlags(args);
+    const { status, reauth, valid } = (0, login_flags_1.parseLoginFlags)(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;
+    const readSessionFn = options.readSession ?? session_1.readAuthSession;
+    const writeSessionFn = options.writeSession ?? session_1.writeAuthSession;
+    const clearSessionFn = options.clearSession ?? session_1.clearAuthSession;
     try {
         const config = requireConfig(options.env ?? process.env);
         if (status) {
-            return printSessionStatus(readSessionFn(), config.firebaseProjectId);
-        }
-        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) {
-                    const project = formatSessionProject(existingSession, config.firebaseProjectId);
-                    if (existingSession.email) {
-                        console.log(`Already logged in as ${existingSession.email} (project: ${project.label}). ` +
-                            "Run 'skillmd logout' first.");
-                    }
-                    else {
-                        console.log(`Already logged in (uid: ${existingSession.uid}, project: ${project.label}). ` +
-                            "Run 'skillmd logout' first.");
-                    }
-                    if (project.mismatch) {
-                        console.log(`Current CLI config targets project '${config.firebaseProjectId}'. ` +
-                            "Run 'skillmd login --reauth' to switch projects.");
-                    }
-                    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;
-            }
+            return (0, login_status_1.printSessionStatus)(readSessionFn(), config.firebaseProjectId);
         }
-        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,
-            projectId: config.firebaseProjectId,
+        return await (0, login_flow_1.executeLoginFlow)(config, reauth, {
+            readSession: readSessionFn,
+            writeSession: writeSessionFn,
+            clearSession: clearSessionFn,
+            requestDeviceCode: options.requestDeviceCode ?? github_device_flow_1.requestDeviceCode,
+            pollForAccessToken: options.pollForAccessToken ?? github_device_flow_1.pollForAccessToken,
+            signInWithGitHubAccessToken: options.signInWithGitHubAccessToken ?? firebase_auth_1.signInWithGitHubAccessToken,
+            verifyRefreshToken: options.verifyRefreshToken ?? firebase_auth_1.verifyFirebaseRefreshToken,
         });
-        if (firebaseSession.email) {
-            console.log(`Login successful. Signed in as ${firebaseSession.email} (project: ${config.firebaseProjectId}).`);
-        }
-        else {
-            console.log(`Login successful (project: ${config.firebaseProjectId}).`);
-        }
-        return 0;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";

package/dist/commands/logout.js

@@ -1,19 +1,26 @@
 "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");
+const cli_text_1 = require("../lib/shared/cli-text");
+const command_output_1 = require("../lib/shared/command-output");
+const 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.");
+    try {
+        const clearSessionFn = options.clearSession ?? session_1.clearAuthSession;
+        const removed = clearSessionFn();
+        if (removed) {
+            console.log("Logged out.");
+            return 0;
+        }
+        console.log("No active session to log out.");
         return 0;
     }
-    console.log("No active session to log out.");
-    return 0;
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        console.error(`skillmd logout: ${message}`);
+        return 1;
+    }
 }

package/dist/commands/validate.js

@@ -2,61 +2,68 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runValidateCommand = runValidateCommand;
 const node_path_1 = require("node:path");
-const cli_text_1 = require("../lib/cli-text");
-const command_output_1 = require("../lib/command-output");
-const upstream_validator_1 = require("../lib/upstream-validator");
-const validator_1 = require("../lib/validator");
+const cli_text_1 = require("../lib/shared/cli-text");
+const command_output_1 = require("../lib/shared/command-output");
+const upstream_validator_1 = require("../lib/validation/upstream-validator");
+const validator_1 = require("../lib/validation/validator");
 function runValidateCommand(args, options = {}) {
-    const cwd = options.cwd ?? process.cwd();
-    const validateLocal = options.validateLocal ?? validator_1.validateSkill;
-    const validateUpstream = options.validateUpstream ?? upstream_validator_1.validateWithSkillsRef;
-    let strict = false;
-    let parity = false;
-    let pathArg;
-    for (const arg of args) {
-        if (arg === "--strict") {
-            strict = true;
-            continue;
+    try {
+        const cwd = options.cwd ?? process.cwd();
+        const validateLocal = options.validateLocal ?? validator_1.validateSkill;
+        const validateUpstream = options.validateUpstream ?? upstream_validator_1.validateWithSkillsRef;
+        let strict = false;
+        let parity = false;
+        let pathArg;
+        for (const arg of args) {
+            if (arg === "--strict") {
+                strict = true;
+                continue;
+            }
+            if (arg === "--parity") {
+                parity = true;
+                continue;
+            }
+            if (arg.startsWith("-")) {
+                return (0, command_output_1.failWithUsage)(`skillmd validate: unsupported flag '${arg}'`, cli_text_1.VALIDATE_USAGE);
+            }
+            if (pathArg) {
+                return (0, command_output_1.failWithUsage)("skillmd validate: accepts at most one path argument", cli_text_1.VALIDATE_USAGE);
+            }
+            pathArg = arg;
         }
-        if (arg === "--parity") {
-            parity = true;
-            continue;
-        }
-        if (arg.startsWith("-")) {
-            return (0, command_output_1.failWithUsage)(`skillmd validate: unsupported flag '${arg}'`, cli_text_1.VALIDATE_USAGE);
-        }
-        if (pathArg) {
-            return (0, command_output_1.failWithUsage)("skillmd validate: accepts at most one path argument", cli_text_1.VALIDATE_USAGE);
-        }
-        pathArg = arg;
-    }
-    const targetDir = pathArg ? (0, node_path_1.resolve)(cwd, pathArg) : cwd;
-    const validation = validateLocal(targetDir, { strict });
-    if (parity) {
-        const upstream = validateUpstream(targetDir);
-        if (upstream.status === "unavailable") {
-            console.error(`Validation parity unavailable: ${upstream.message}. Install skills-ref to use --parity.`);
-            return 1;
-        }
-        if (validation.status === "passed" && upstream.status !== "passed") {
-            console.error("Validation parity mismatch: local validation passed but skills-ref failed.");
-            console.error(`skills-ref: ${upstream.message}`);
-            return 1;
+        const targetDir = pathArg ? (0, node_path_1.resolve)(cwd, pathArg) : cwd;
+        const validation = validateLocal(targetDir, { strict });
+        if (parity) {
+            const upstream = validateUpstream(targetDir);
+            if (upstream.status === "unavailable") {
+                console.error(`Validation parity unavailable: ${upstream.message}. Install skills-ref to use --parity.`);
+                return 1;
+            }
+            if (validation.status === "passed" && upstream.status !== "passed") {
+                console.error("Validation parity mismatch: local validation passed but skills-ref failed.");
+                console.error(`skills-ref: ${upstream.message}`);
+                return 1;
+            }
+            if (validation.status === "failed" && upstream.status !== "failed") {
+                console.error("Validation parity mismatch: local validation failed but skills-ref passed.");
+                return 1;
+            }
         }
-        if (validation.status === "failed" && upstream.status !== "failed") {
-            console.error("Validation parity mismatch: local validation failed but skills-ref passed.");
-            return 1;
+        (0, command_output_1.printValidationResult)(validation);
+        if (validation.status === "passed") {
+            if (parity) {
+                console.log("Validation parity passed (skills-ref).");
+            }
+            return 0;
         }
-    }
-    (0, command_output_1.printValidationResult)(validation);
-    if (validation.status === "passed") {
         if (parity) {
-            console.log("Validation parity passed (skills-ref).");
+            console.error("Validation parity matched (skills-ref also failed).");
         }
-        return 0;
+        return 1;
     }
-    if (parity) {
-        console.error("Validation parity matched (skills-ref also failed).");
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        console.error(`skillmd validate: ${message}`);
+        return 1;
     }
-    return 1;
 }

package/dist/lib/{auth-config.js → auth/config.js}

@@ -5,7 +5,7 @@ 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 defaults_1 = require("./defaults");
 const USER_ENV_RELATIVE_PATH = ".skillmd/.env";
 function parseDotEnv(content) {
     const values = {};
@@ -52,9 +52,9 @@ function pickValue(...candidates) {
 }
 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);
-    const firebaseProjectId = pickValue(env.SKILLMD_FIREBASE_PROJECT_ID, dotEnv.SKILLMD_FIREBASE_PROJECT_ID, auth_defaults_1.DEFAULT_LOGIN_AUTH_CONFIG.firebaseProjectId);
+    const githubClientId = pickValue(env.SKILLMD_GITHUB_CLIENT_ID, dotEnv.SKILLMD_GITHUB_CLIENT_ID, defaults_1.DEFAULT_LOGIN_AUTH_CONFIG.githubClientId);
+    const firebaseApiKey = pickValue(env.SKILLMD_FIREBASE_API_KEY, dotEnv.SKILLMD_FIREBASE_API_KEY, defaults_1.DEFAULT_LOGIN_AUTH_CONFIG.firebaseApiKey);
+    const firebaseProjectId = pickValue(env.SKILLMD_FIREBASE_PROJECT_ID, dotEnv.SKILLMD_FIREBASE_PROJECT_ID, defaults_1.DEFAULT_LOGIN_AUTH_CONFIG.firebaseProjectId);
     if (!githubClientId || !firebaseApiKey || !firebaseProjectId) {
         throw new Error("missing login configuration");
     }

package/dist/lib/{firebase-auth.js → auth/firebase-auth.js}

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.signInWithGitHubAccessToken = signInWithGitHubAccessToken;
 exports.verifyFirebaseRefreshToken = verifyFirebaseRefreshToken;
-const http_1 = require("./http");
+const http_1 = require("../shared/http");
 const FIREBASE_HTTP_TIMEOUT_MS = 10000;
 async function parseJsonApiResponse(response, apiLabel) {
     const text = await response.text();

package/dist/lib/{github-device-flow.js → auth/github-device-flow.js}

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.requestDeviceCode = requestDeviceCode;
 exports.pollForAccessToken = pollForAccessToken;
-const http_1 = require("./http");
+const http_1 = require("../shared/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;

package/dist/lib/auth/login-flags.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseLoginFlags = parseLoginFlags;
+function parseLoginFlags(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 };
+}

package/dist/lib/auth/login-flow.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeLoginFlow = executeLoginFlow;
+const login_status_1 = require("./login-status");
+async function executeLoginFlow(config, reauth, dependencies) {
+    const existingSession = dependencies.readSession();
+    if (existingSession && !reauth) {
+        try {
+            const validation = await dependencies.verifyRefreshToken(config.firebaseApiKey, existingSession.refreshToken);
+            if (validation.valid) {
+                const project = (0, login_status_1.formatSessionProject)(existingSession, config.firebaseProjectId);
+                if (existingSession.email) {
+                    console.log(`Already logged in as ${existingSession.email} (project: ${project.label}). ` +
+                        "Run 'skillmd logout' first.");
+                }
+                else {
+                    console.log(`Already logged in (uid: ${existingSession.uid}, project: ${project.label}). ` +
+                        "Run 'skillmd logout' first.");
+                }
+                if (project.mismatch) {
+                    console.log(`Current CLI config targets project '${config.firebaseProjectId}'. ` +
+                        "Run 'skillmd login --reauth' to switch projects.");
+                }
+                return 0;
+            }
+            dependencies.clearSession();
+            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 deviceCode = await dependencies.requestDeviceCode(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 dependencies.pollForAccessToken(config.githubClientId, deviceCode.deviceCode, deviceCode.interval, deviceCode.expiresIn);
+    const firebaseSession = await dependencies.signInWithGitHubAccessToken(config.firebaseApiKey, token.accessToken);
+    dependencies.writeSession({
+        provider: "github",
+        uid: firebaseSession.localId,
+        email: firebaseSession.email,
+        refreshToken: firebaseSession.refreshToken,
+        projectId: config.firebaseProjectId,
+    });
+    if (firebaseSession.email) {
+        console.log(`Login successful. Signed in as ${firebaseSession.email} (project: ${config.firebaseProjectId}).`);
+    }
+    else {
+        console.log(`Login successful (project: ${config.firebaseProjectId}).`);
+    }
+    return 0;
+}

package/dist/lib/auth/login-status.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSessionProject = formatSessionProject;
+exports.printSessionStatus = printSessionStatus;
+function formatSessionProject(session, currentConfigProjectId) {
+    if (!session.projectId) {
+        if (currentConfigProjectId) {
+            return { label: `unknown (current config: ${currentConfigProjectId})`, mismatch: false };
+        }
+        return { label: "unknown", mismatch: false };
+    }
+    return {
+        label: session.projectId,
+        mismatch: Boolean(currentConfigProjectId && session.projectId !== currentConfigProjectId),
+    };
+}
+function printSessionStatus(session, currentConfigProjectId) {
+    if (!session) {
+        console.log("Not logged in.");
+        return 1;
+    }
+    const project = formatSessionProject(session, currentConfigProjectId);
+    if (session.email) {
+        console.log(`Logged in with GitHub as ${session.email} (project: ${project.label}).`);
+    }
+    else {
+        console.log(`Logged in with GitHub (uid: ${session.uid}, project: ${project.label}).`);
+    }
+    if (project.mismatch && currentConfigProjectId) {
+        console.log(`Current CLI config targets project '${currentConfigProjectId}'. ` +
+            "Run 'skillmd login --reauth' to switch projects.");
+    }
+    return 0;
+}

package/dist/lib/scaffold/scaffold.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInitTemplateId = isInitTemplateId;
+exports.resolveInitTemplateId = resolveInitTemplateId;
+exports.scaffoldSkillInDirectory = scaffoldSkillInDirectory;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const normalize_name_1 = require("./normalize-name");
+const skill_spec_1 = require("./skill-spec");
+const templates_1 = require("./templates");
+function assertDirectoryEmpty(targetDir) {
+    const entries = (0, node_fs_1.readdirSync)(targetDir);
+    if (entries.length > 0) {
+        throw new Error(`target directory is not empty (${entries.length} item(s) found); run 'skillmd init' in an empty directory`);
+    }
+}
+function assertDirectoryNameMatchesNormalized(targetDir) {
+    const dirName = (0, node_path_1.basename)(targetDir);
+    const normalizedName = (0, normalize_name_1.normalizeSkillName)(dirName);
+    if (dirName !== normalizedName) {
+        throw new Error(`directory name '${dirName}' must already be normalized. Rename it to '${normalizedName}' and retry`);
+    }
+    return normalizedName;
+}
+function isInitTemplateId(value) {
+    return skill_spec_1.INIT_TEMPLATE_IDS.includes(value);
+}
+function resolveInitTemplateId(value) {
+    return isInitTemplateId(value) ? value : null;
+}
+function createDirectory(path, createdPaths) {
+    (0, node_fs_1.mkdirSync)(path, { recursive: false, mode: 0o755 });
+    createdPaths.push({ kind: "dir", path });
+}
+function createFile(path, content, createdPaths) {
+    (0, node_fs_1.writeFileSync)(path, content, { encoding: "utf8", flag: "wx", mode: 0o644 });
+    (0, node_fs_1.chmodSync)(path, 0o644);
+    createdPaths.push({ kind: "file", path });
+}
+function rollbackCreatedPaths(createdPaths) {
+    for (const entry of [...createdPaths].reverse()) {
+        if (entry.kind === "file") {
+            (0, node_fs_1.rmSync)(entry.path, { force: true });
+            continue;
+        }
+        (0, node_fs_1.rmSync)(entry.path, { recursive: true, force: true });
+    }
+}
+function scaffoldSkillInDirectory(targetDir, options = {}) {
+    const template = options.template ?? "minimal";
+    const skillName = assertDirectoryNameMatchesNormalized(targetDir);
+    assertDirectoryEmpty(targetDir);
+    const createdPaths = [];
+    try {
+        if (template === "verbose") {
+            for (const directory of skill_spec_1.SCAFFOLD_DIRECTORIES) {
+                const fullPath = (0, node_path_1.join)(targetDir, directory);
+                createDirectory(fullPath, createdPaths);
+                createFile((0, node_path_1.join)(fullPath, ".gitkeep"), "", createdPaths);
+            }
+            createFile((0, node_path_1.join)(targetDir, ".gitignore"), (0, templates_1.buildGitignore)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "SKILL.md"), (0, templates_1.buildVerboseSkillMarkdown)(skillName), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "scripts", "README.md"), (0, templates_1.buildScriptsReadme)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "scripts", "extract.py"), (0, templates_1.buildExtractScriptPython)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "references", "REFERENCE.md"), (0, templates_1.buildReferenceGuide)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "references", "FORMS.md"), (0, templates_1.buildFormsReference)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "assets", "README.md"), (0, templates_1.buildAssetsReadme)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "assets", "report-template.md"), (0, templates_1.buildReportTemplate)(), createdPaths);
+            createFile((0, node_path_1.join)(targetDir, "assets", "lookup-table.csv"), (0, templates_1.buildLookupTableCsv)(), createdPaths);
+            return { skillName, template };
+        }
+        createFile((0, node_path_1.join)(targetDir, "SKILL.md"), (0, templates_1.buildMinimalSkillMarkdown)(skillName), createdPaths);
+        return { skillName, template };
+    }
+    catch (error) {
+        rollbackCreatedPaths(createdPaths);
+        throw error;
+    }
+}

package/dist/lib/{skill-spec.js → scaffold/skill-spec.js}

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STRICT_SECTION_HEADINGS = exports.STRICT_SECTION_TITLES = exports.STRICT_REQUIRED_FILES = exports.SCAFFOLD_DIRECTORIES = exports.MAX_SKILL_NAME_LENGTH = void 0;
+exports.STRICT_SECTION_HEADINGS = exports.STRICT_SECTION_TITLES = exports.STRICT_REQUIRED_FILES = exports.SCAFFOLD_DIRECTORIES = exports.INIT_TEMPLATE_IDS = exports.MAX_SKILL_NAME_LENGTH = void 0;
 exports.MAX_SKILL_NAME_LENGTH = 64;
+exports.INIT_TEMPLATE_IDS = ["minimal", "verbose"];
 exports.SCAFFOLD_DIRECTORIES = ["scripts", "references", "assets"];
 exports.STRICT_REQUIRED_FILES = [
     ".gitignore",

package/dist/lib/scaffold/templates/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./skill-markdown"), exports);
+__exportStar(require("./resources"), exports);

package/dist/lib/scaffold/templates/resources.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildGitignore = buildGitignore;
+exports.buildScriptsReadme = buildScriptsReadme;
+exports.buildExtractScriptPython = buildExtractScriptPython;
+exports.buildReferenceGuide = buildReferenceGuide;
+exports.buildFormsReference = buildFormsReference;
+exports.buildAssetsReadme = buildAssetsReadme;
+exports.buildReportTemplate = buildReportTemplate;
+exports.buildLookupTableCsv = buildLookupTableCsv;
+function buildGitignore() {
+    return `node_modules/
+dist/
+.DS_Store
+npm-debug.log*
+`;
+}
+function buildScriptsReadme() {
+    return `# scripts/
+
+Use this folder for executable code that agents can run.
+
+Guidelines:
+- Keep scripts self-contained or clearly document dependencies.
+- Emit actionable error messages.
+- Handle edge cases (missing files, invalid input, empty data).
+
+Starter script:
+- \`scripts/extract.py\`
+`;
+}
+function buildExtractScriptPython() {
+    return `#!/usr/bin/env python3
+"""Example extraction script with defensive error handling.
+
+Usage:
+  python3 scripts/extract.py --input ./input.txt --output ./output.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Extract line and word statistics.")
+    parser.add_argument("--input", required=True, help="Path to input text file.")
+    parser.add_argument("--output", required=True, help="Path to output JSON file.")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    if not os.path.exists(args.input):
+        print(f"error: input file does not exist: {args.input}", file=sys.stderr)
+        return 1
+
+    try:
+        with open(args.input, "r", encoding="utf-8") as source:
+            content = source.read()
+    except OSError as error:
+        print(f"error: failed to read input file: {error}", file=sys.stderr)
+        return 1
+
+    lines = [line for line in content.splitlines() if line.strip()]
+    result = {
+        "line_count": len(lines),
+        "word_count": len(content.split()),
+        "preview": lines[:3],
+    }
+
+    try:
+        with open(args.output, "w", encoding="utf-8") as destination:
+            json.dump(result, destination, indent=2)
+            destination.write("\\n")
+    except OSError as error:
+        print(f"error: failed to write output file: {error}", file=sys.stderr)
+        return 1
+
+    print(f"wrote extraction summary to {args.output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+`;
+}
+function buildReferenceGuide() {
+    return `# Reference Guide
+
+Use this file for detailed technical reference that should not live in \`SKILL.md\`.
+
+Suggested sections:
+- Data model and field definitions
+- Validation rules and constraints
+- External API contract notes
+- Error catalog and recovery guidance
+
+Keep this file focused and concise. Add deeper detail in additional reference files when needed.
+`;
+}
+function buildFormsReference() {
+    return `# Forms and Structured Templates
+
+Use this file to store reusable form structures and payload templates.
+
+## Intake Form (Example)
+
+\`\`\`yaml
+request_id: "REQ-0001"
+request_type: "analysis"
+priority: "normal"
+inputs:
+  source_path: "./input.txt"
+  output_path: "./output.json"
+\`\`\`
+
+## Result Envelope (Example)
+
+\`\`\`json
+{
+  "status": "ok",
+  "summary": "One-line result summary",
+  "artifacts": []
+}
+\`\`\`
+`;
+}
+function buildAssetsReadme() {
+    return `# assets/
+
+Use this folder for static resources that scripts or instructions can reference:
+- templates
+- lookup tables
+- example data
+- diagrams
+
+Keep asset files small and task-focused.
+`;
+}
+function buildReportTemplate() {
+    return `# Report Template
+
+## Summary
+- Status:
+- Owner:
+- Updated:
+
+## Findings
+1.
+2.
+3.
+
+## Next Steps
+1.
+2.
+`;
+}
+function buildLookupTableCsv() {
+    return `code,label,description
+E001,missing_input,Required input file is missing
+E002,invalid_format,Input format is invalid or unsupported
+E003,write_failed,Output could not be written
+`;
+}

package/dist/lib/scaffold/templates/skill-markdown.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSkillMarkdown = buildSkillMarkdown;
+exports.buildMinimalSkillMarkdown = buildMinimalSkillMarkdown;
+exports.buildVerboseSkillMarkdown = buildVerboseSkillMarkdown;
+const skill_spec_1 = require("../skill-spec");
+const SECTION_PLACEHOLDERS = {
+    Scope: "Define the boundaries of this skill: what it should and should not handle.",
+    "When to use": "Describe the signals or request patterns that should trigger this skill. Keep SKILL.md focused and move deep details into references/ files.",
+    Inputs: "List required and optional inputs, expected formats, and assumptions. Add structured templates to references/FORMS.md when helpful.",
+    Outputs: "Describe expected outputs, side effects, and completion criteria. Use assets/report-template.md when a fixed output structure is useful.",
+    "Steps / Procedure": "Provide ordered steps the agent should follow, including key decision points. See [the reference guide](references/REFERENCE.md) for detailed rules. Run helper scripts such as scripts/extract.py when needed.",
+    Examples: "Add one or two realistic examples of inputs and expected outputs.",
+    "Limitations / Failure modes": "Document known limitations, failure cases, and recommended recovery actions.",
+    "Security / Tool access": "State required tools/permissions and any security constraints. If needed, set frontmatter allowed-tools to pre-approve tool usage.",
+};
+function buildSkillMarkdown(name) {
+    const sections = skill_spec_1.STRICT_SECTION_TITLES.map((title) => `## ${title}\n\n${SECTION_PLACEHOLDERS[title]}`).join("\n\n");
+    return `---
+name: ${name}
+description: Explain what this skill does and when an agent should use it.
+# compatibility: "Optional: environment requirements (products, packages, network access)."
+# metadata:
+#   author: "your-org"
+#   version: "1.0.0"
+# allowed-tools: "Optional: space-delimited pre-approved tools."
+license: Optional. Add a license name or reference to a bundled license file.
+---
+
+${sections}
+`;
+}
+function buildMinimalSkillMarkdown(name) {
+    return buildSkillMarkdown(name);
+}
+function buildVerboseSkillMarkdown(name) {
+    return buildSkillMarkdown(name);
+}

package/dist/lib/{cli-text.js → shared/cli-text.js}

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 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.INIT_USAGE = "Usage: skillmd init [--no-validate] [--template <minimal|verbose>]";
 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/{upstream-validator.js → validation/upstream-validator.js}

@@ -2,12 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateWithSkillsRef = validateWithSkillsRef;
 const node_child_process_1 = require("node:child_process");
+const SKILLS_REF_TIMEOUT_MS = 10000;
 function formatOutput(stdout, stderr) {
     return [stdout.trim(), stderr.trim()].filter((part) => part.length > 0).join("\n");
 }
 function validateWithSkillsRef(targetDir) {
     const result = (0, node_child_process_1.spawnSync)("skills-ref", ["validate", targetDir], {
         encoding: "utf8",
+        timeout: SKILLS_REF_TIMEOUT_MS,
     });
     if (result.error) {
         if ("code" in result.error && result.error.code === "ENOENT") {
@@ -16,6 +18,12 @@ function validateWithSkillsRef(targetDir) {
                 message: "skills-ref is not installed or not on PATH",
             };
         }
+        if ("code" in result.error && result.error.code === "ETIMEDOUT") {
+            return {
+                status: "unavailable",
+                message: `skills-ref timed out after ${SKILLS_REF_TIMEOUT_MS}ms`,
+            };
+        }
         return {
             status: "unavailable",
             message: `skills-ref execution failed: ${result.error.message}`,

package/dist/lib/{validator.js → validation/validator.js}

@@ -4,7 +4,7 @@ exports.validateSkill = validateSkill;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const yaml_1 = require("yaml");
-const skill_spec_1 = require("./skill-spec");
+const skill_spec_1 = require("../scaffold/skill-spec");
 const SKILL_FILE = "SKILL.md";
 function stripUtf8Bom(content) {
     return content.replace(/^\uFEFF/, "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillmarkdown/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "CLI for scaffolding SKILL.md-based AI skills",
   "license": "MIT",
   "type": "commonjs",
@@ -25,7 +25,7 @@
     "prepublishOnly": "npm run clean && npm run build",
     "smoke:link": "bash ./scripts/smoke-link.sh",
     "smoke:pack": "bash ./scripts/smoke-pack.sh",
-    "test": "npm run build && node --test tests/*.test.js"
+    "test": "npm run build && node --test \"tests/**/*.test.js\""
   },
   "engines": {
     "node": ">=18"

package/dist/lib/scaffold.js

@@ -1,34 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.scaffoldSkillInDirectory = scaffoldSkillInDirectory;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const normalize_name_1 = require("./normalize-name");
-const skill_spec_1 = require("./skill-spec");
-const templates_1 = require("./templates");
-function assertDirectoryEmpty(targetDir) {
-    const entries = (0, node_fs_1.readdirSync)(targetDir);
-    if (entries.length > 0) {
-        throw new Error(`target directory is not empty (${entries.length} item(s) found); run 'skillmd init' in an empty directory`);
-    }
-}
-function assertDirectoryNameMatchesNormalized(targetDir) {
-    const dirName = (0, node_path_1.basename)(targetDir);
-    const normalizedName = (0, normalize_name_1.normalizeSkillName)(dirName);
-    if (dirName !== normalizedName) {
-        throw new Error(`directory name '${dirName}' must already be normalized. Rename it to '${normalizedName}' and retry`);
-    }
-    return normalizedName;
-}
-function scaffoldSkillInDirectory(targetDir) {
-    const skillName = assertDirectoryNameMatchesNormalized(targetDir);
-    assertDirectoryEmpty(targetDir);
-    for (const directory of skill_spec_1.SCAFFOLD_DIRECTORIES) {
-        const fullPath = (0, node_path_1.join)(targetDir, directory);
-        (0, node_fs_1.mkdirSync)(fullPath, { recursive: true });
-        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(fullPath, ".gitkeep"), "", "utf8");
-    }
-    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(targetDir, "SKILL.md"), (0, templates_1.buildSkillMarkdown)(skillName), "utf8");
-    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(targetDir, ".gitignore"), (0, templates_1.buildGitignore)(), "utf8");
-    return { skillName };
-}

package/dist/lib/templates.js

@@ -1,23 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildSkillMarkdown = buildSkillMarkdown;
-exports.buildGitignore = buildGitignore;
-const skill_spec_1 = require("./skill-spec");
-function buildSkillMarkdown(name) {
-    const sections = skill_spec_1.STRICT_SECTION_TITLES.map((title) => `## ${title}\nTODO`).join("\n\n");
-    return `---
-name: ${name}
-description: "TODO: Describe what this skill does and when to use it."
-license: TODO
----
-
-${sections}
-`;
-}
-function buildGitignore() {
-    return `node_modules/
-dist/
-.DS_Store
-npm-debug.log*
-`;
-}