@spekn/cli 1.0.0 → 1.0.1

package/dist/commands/skills-import-local.d.ts

@@ -1,16 +0,0 @@
-/**
- * skills import-local CLI command
- *
- * Imports SKILL.md files from a local directory into a Spekn project.
- *
- * Usage: spekn skills import-local <path> --project-id <uuid> [--namespace <ns>] [--api-url <url>]
- */
-import { CredentialsStore } from "../auth/credentials-store";
-interface Deps {
-    stdout: (content: string) => void;
-    stderr: (content: string) => void;
-    credentialsStore: CredentialsStore;
-}
-export declare function runSkillsImportLocalCli(args: string[], deps?: Deps): Promise<number>;
-export declare function main(): Promise<void>;
-export {};

package/dist/commands/skills-import-local.js

@@ -1,352 +0,0 @@
-"use strict";
-/**
- * skills import-local CLI command
- *
- * Imports SKILL.md files from a local directory into a Spekn project.
- *
- * Usage: spekn skills import-local <path> --project-id <uuid> [--namespace <ns>] [--api-url <url>]
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runSkillsImportLocalCli = runSkillsImportLocalCli;
-exports.main = main;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const client_1 = require("@trpc/client");
-const shared_1 = require("@spekn/shared");
-const credentials_store_1 = require("../auth/credentials-store");
-const project_context_1 = require("../project-context");
-const structured_log_1 = require("../utils/structured-log");
-const trpc_url_1 = require("../utils/trpc-url");
-const help_error_1 = require("../utils/help-error");
-const defaultDeps = {
-    stdout: (content) => process.stdout.write(content),
-    stderr: (content) => process.stderr.write(content),
-    credentialsStore: new credentials_store_1.CredentialsStore(),
-};
-function printHelp(stderr) {
-    stderr(`
-skills import-local - Import SKILL.md files from a local directory
-
-USAGE:
-  spekn skills import-local <path> --project-id <uuid> [options]
-
-ARGUMENTS:
-  <path>                Directory containing SKILL.md files (searched recursively)
-
-OPTIONS:
-  --project-id <uuid>   Project ID to import skills into (optional if .spekn/context is present)
-  --namespace <ns>      Namespace for imported skills (default: directory name)
-  --names <a,b,c>       Comma-separated skill names to import (default: all)
-  --api-url <url>       API base URL (default: SPEKN_API_URL or https://app.spekn.com)
-  --help                Show this help message
-
-ENVIRONMENT:
-  SPEKN_API_URL         API base URL
-  SPEKN_AUTH_TOKEN      Bearer token for authentication
-  SPEKN_ORGANIZATION_ID Organization ID header
-
-EXAMPLES:
-  spekn skills import-local ./my-skills --project-id 11111111-1111-4111-8111-111111111111
-  spekn skills import-local ./plugins/skills --project-id <uuid> --namespace my-org
-`);
-}
-function parseArgs(args) {
-    let path = "";
-    let projectId = "";
-    let namespace = "";
-    let names = [];
-    let apiUrl = process.env.SPEKN_API_URL ?? "https://app.spekn.com";
-    for (let index = 0; index < args.length; index++) {
-        const arg = args[index];
-        if (arg === "--help" || arg === "-h") {
-            throw new help_error_1.HelpRequestedError();
-        }
-        if (arg === "--project-id" && args[index + 1]) {
-            projectId = args[++index];
-            continue;
-        }
-        if (arg?.startsWith("--project-id=")) {
-            projectId = arg.slice("--project-id=".length);
-            continue;
-        }
-        if (arg === "--namespace" && args[index + 1]) {
-            namespace = args[++index];
-            continue;
-        }
-        if (arg?.startsWith("--namespace=")) {
-            namespace = arg.slice("--namespace=".length);
-            continue;
-        }
-        if (arg === "--names" && args[index + 1]) {
-            names = args[++index].split(",").map((n) => n.trim()).filter(Boolean);
-            continue;
-        }
-        if (arg?.startsWith("--names=")) {
-            names = arg.slice("--names=".length).split(",").map((n) => n.trim()).filter(Boolean);
-            continue;
-        }
-        if (arg === "--api-url" && args[index + 1]) {
-            apiUrl = args[++index];
-            continue;
-        }
-        if (arg?.startsWith("--api-url=")) {
-            apiUrl = arg.slice("--api-url=".length);
-            continue;
-        }
-        // Positional argument: path
-        if (!arg?.startsWith("--") && !path) {
-            path = arg;
-        }
-    }
-    if (!path) {
-        throw new Error("Missing required argument: <path>");
-    }
-    const resolvedPath = (0, node_path_1.resolve)(path);
-    if (!namespace) {
-        namespace = (0, node_path_1.basename)(resolvedPath);
-    }
-    return { path: resolvedPath, projectId, namespace, names, apiUrl };
-}
-/**
- * Recursively find all SKILL.md files under a directory.
- */
-function findSkillFiles(dir) {
-    const results = [];
-    const entries = (0, node_fs_1.readdirSync)(dir);
-    for (const entry of entries) {
-        const fullPath = (0, node_path_1.join)(dir, entry);
-        const stat = (0, node_fs_1.statSync)(fullPath);
-        if (stat.isDirectory()) {
-            results.push(...findSkillFiles(fullPath));
-        }
-        else if (entry === "SKILL.md") {
-            results.push(fullPath);
-        }
-    }
-    return results;
-}
-/**
- * Recursively collect all files in a skill directory and return a map
- * of relative paths to file contents.
- */
-function collectSkillFiles(skillDir) {
-    const files = {};
-    function walk(dir) {
-        const entries = (0, node_fs_1.readdirSync)(dir);
-        for (const entry of entries) {
-            const fullPath = (0, node_path_1.join)(dir, entry);
-            const stat = (0, node_fs_1.statSync)(fullPath);
-            if (stat.isDirectory()) {
-                walk(fullPath);
-            }
-            else {
-                const relPath = (0, node_path_1.relative)(skillDir, fullPath);
-                files[relPath] = (0, node_fs_1.readFileSync)(fullPath, "utf-8");
-            }
-        }
-    }
-    walk(skillDir);
-    return files;
-}
-/**
- * Parse a SKILL.md file: extract YAML frontmatter and body content.
- */
-function parseSkillFile(filePath) {
-    const content = (0, node_fs_1.readFileSync)(filePath, "utf-8");
-    const fmMatch = /^---\n([\s\S]*?)\n---/.exec(content);
-    if (!fmMatch?.[1]) {
-        return { error: `${filePath}: no frontmatter found` };
-    }
-    // Simple YAML parsing without js-yaml dependency.
-    // SKILL.md frontmatter is flat key-value, so we parse it manually.
-    const yamlText = fmMatch[1];
-    const frontmatter = {};
-    let currentKey = "";
-    let inNestedMap = false;
-    const nestedMap = {};
-    for (const line of yamlText.split("\n")) {
-        // Nested map value (indented)
-        if (inNestedMap && /^\s{2,}\S/.test(line)) {
-            const kvMatch = /^\s+(\S+):\s*(.*)$/.exec(line);
-            if (kvMatch) {
-                nestedMap[kvMatch[1]] = kvMatch[2].replace(/^["']|["']$/g, "");
-            }
-            continue;
-        }
-        // Flush nested map if we were in one
-        if (inNestedMap) {
-            frontmatter[currentKey] = { ...nestedMap };
-            for (const k of Object.keys(nestedMap))
-                delete nestedMap[k];
-            inNestedMap = false;
-        }
-        // Top-level key: value
-        const topMatch = /^(\S+):\s*(.*)$/.exec(line);
-        if (topMatch) {
-            const key = topMatch[1];
-            const value = topMatch[2].replace(/^["']|["']$/g, "");
-            if (value === "" || value === undefined) {
-                // Could be start of a nested map
-                currentKey = key;
-                inNestedMap = true;
-            }
-            else {
-                frontmatter[key] = value;
-            }
-        }
-    }
-    // Flush last nested map
-    if (inNestedMap) {
-        frontmatter[currentKey] = { ...nestedMap };
-    }
-    // Extract readme (content after frontmatter)
-    const readme = content.slice(fmMatch[0].length).trim();
-    return { frontmatter, readme };
-}
-async function runSkillsImportLocalCli(args, deps = defaultDeps) {
-    try {
-        const options = parseArgs(args);
-        (0, structured_log_1.appendCliStructuredLog)({
-            source: "cli.skills.import-local",
-            level: "info",
-            message: "Starting skills import-local",
-            details: { path: options.path, namespace: options.namespace, apiUrl: options.apiUrl },
-        });
-        // Find SKILL.md files
-        const skillFiles = findSkillFiles(options.path);
-        if (skillFiles.length === 0) {
-            deps.stderr(`No SKILL.md files found under ${options.path}\n`);
-            return 1;
-        }
-        deps.stdout(`Found ${skillFiles.length} SKILL.md file(s) in ${options.path}\n`);
-        // Parse and validate each file
-        const skills = [];
-        const parseErrors = [];
-        for (const filePath of skillFiles) {
-            const result = parseSkillFile(filePath);
-            if ("error" in result) {
-                parseErrors.push(result.error);
-                continue;
-            }
-            const validation = shared_1.SkillFrontmatterSchema.safeParse(result.frontmatter);
-            if (!validation.success) {
-                const issues = validation.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
-                parseErrors.push(`${filePath}: ${issues.join("; ")}`);
-                continue;
-            }
-            const fm = validation.data;
-            const meta = fm.metadata;
-            const skillDir = (0, node_path_1.dirname)(filePath);
-            const files = collectSkillFiles(skillDir);
-            skills.push({
-                name: fm.name,
-                description: fm.description,
-                version: meta?.version || "0.0.0",
-                namespace: options.namespace,
-                readme: result.readme || undefined,
-                license: fm.license,
-                compatibility: fm.compatibility,
-                author: meta?.author,
-                tags: [],
-                metadata: meta ? { ...meta } : undefined,
-                files,
-            });
-        }
-        if (parseErrors.length > 0) {
-            deps.stderr(`\nParse errors:\n`);
-            for (const err of parseErrors) {
-                deps.stderr(`  - ${err}\n`);
-            }
-        }
-        // Filter by --names if provided
-        if (options.names.length > 0) {
-            const nameSet = new Set(options.names);
-            const before = skills.length;
-            const filtered = skills.filter((s) => nameSet.has(s.name));
-            skills.length = 0;
-            skills.push(...filtered);
-            if (skills.length < before) {
-                deps.stdout(`Filtered to ${skills.length} of ${before} skill(s) by --names\n`);
-            }
-        }
-        if (skills.length === 0) {
-            deps.stderr(`No valid skills to import.\n`);
-            return 1;
-        }
-        deps.stdout(`\nImporting ${skills.length} skill(s)...\n`);
-        // Auth
-        const storedToken = await deps.credentialsStore.getValidToken();
-        const authToken = storedToken ?? process.env.SPEKN_AUTH_TOKEN;
-        const storedCreds = deps.credentialsStore.load();
-        const context = (0, project_context_1.resolveProjectContext)({
-            explicitProjectId: options.projectId,
-            repoPath: process.cwd(),
-            credentialsOrganizationId: storedCreds?.organizationId,
-            envOrganizationId: process.env.SPEKN_ORGANIZATION_ID,
-        });
-        // tRPC client
-        const client = (0, client_1.createTRPCProxyClient)({
-            links: [
-                (0, client_1.httpBatchLink)({
-                    url: (0, trpc_url_1.normalizeTrpcUrl)(options.apiUrl),
-                    headers: {
-                        "x-organization-id": context.organizationId,
-                        authorization: authToken ? `Bearer ${authToken}` : "",
-                    },
-                }),
-            ],
-        });
-        const result = await client.skills.importLocal.mutate({
-            projectId: context.projectId,
-            skills,
-        });
-        // Report
-        if (result.imported.length > 0) {
-            deps.stdout(`\nImported: ${result.imported.join(", ")}\n`);
-        }
-        if (result.updated.length > 0) {
-            deps.stdout(`Updated: ${result.updated.join(", ")}\n`);
-        }
-        if (result.errors.length > 0) {
-            deps.stderr(`\nServer errors:\n`);
-            for (const err of result.errors) {
-                deps.stderr(`  - ${err}\n`);
-            }
-        }
-        const total = result.imported.length + result.updated.length;
-        deps.stdout(`\nDone. ${total} skill(s) processed.\n`);
-        (0, structured_log_1.appendCliStructuredLog)({
-            source: "cli.skills.import-local",
-            level: result.errors.length > 0 ? "warn" : "info",
-            message: "Skills import-local completed",
-            details: {
-                totalProcessed: total,
-                imported: result.imported.length,
-                updated: result.updated.length,
-                errors: result.errors.length,
-            },
-        });
-        return result.errors.length > 0 ? 1 : 0;
-    }
-    catch (error) {
-        if (error instanceof help_error_1.HelpRequestedError) {
-            printHelp(deps.stderr);
-            return 0;
-        }
-        const message = error instanceof Error ? error.message : String(error);
-        deps.stderr(`Error: ${message}\n`);
-        (0, structured_log_1.appendCliStructuredLog)({
-            source: "cli.skills.import-local",
-            level: "error",
-            message,
-        });
-        return 1;
-    }
-}
-async function main() {
-    const exitCode = await runSkillsImportLocalCli(process.argv.slice(2));
-    process.exit(exitCode);
-}
-if (require.main === module) {
-    void main();
-}

package/dist/commands/spec/drift-check.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-declare function main(argv?: string[]): Promise<number>;
-export { main };

package/dist/commands/spec/drift-check.js

@@ -1,186 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.main = main;
-const shared_1 = require("@spekn/shared");
-const cli_runtime_1 = require("../../utils/cli-runtime");
-async function columnExists(tableName, columnName) {
-    const rows = (await shared_1.AppDataSource.query(`
-      SELECT 1
-      FROM information_schema.columns
-      WHERE table_schema = current_schema()
-        AND table_name = $1
-        AND column_name = $2
-      LIMIT 1
-    `, [tableName, columnName]));
-    return rows.length > 0;
-}
-function parseArgs(args) {
-    const options = {};
-    for (const arg of args) {
-        if (arg.startsWith("--project-id=")) {
-            options.projectId = arg.split("=")[1];
-        }
-        else if (arg.startsWith("--spec-id=")) {
-            options.specId = arg.split("=")[1];
-        }
-        else if (arg === "--json" || arg === "-j") {
-            options.json = true;
-        }
-        else if (arg === "--verbose" || arg === "-v") {
-            options.verbose = true;
-        }
-    }
-    return options;
-}
-function printHelp() {
-    console.log(`
-spec-drift-check - Fail when task/spec bindings drift
-
-USAGE:
-  npm run spec-drift-check [OPTIONS]
-
-OPTIONS:
-  --project-id=<id>   Filter by project ID
-  --spec-id=<id>      Filter by specification ID
-  -j, --json          Output JSON
-  -v, --verbose       Print individual drift rows
-  -h, --help          Show this help message
-`);
-}
-async function main(argv) {
-    const args = argv ?? process.argv.slice(2);
-    if ((0, cli_runtime_1.hasHelpFlag)(args)) {
-        printHelp();
-        return 0;
-    }
-    const options = parseArgs(args);
-    const hasDbConfig = Boolean(process.env.DATABASE_URL ||
-        process.env.DB_HOST ||
-        process.env.DB_NAME ||
-        process.env.POSTGRES_HOST);
-    if (!hasDbConfig) {
-        console.log("spec-drift-check: skipped (no database configuration found in environment).");
-        return 0;
-    }
-    await shared_1.AppDataSource.initialize();
-    try {
-        const hasTaskSpecVersion = await columnExists("task", "specVersion");
-        const hasTaskSpecRef = await columnExists("task", "specRef");
-        const hasSpecVersion = await columnExists("specification", "version");
-        const hasSpecRef = await columnExists("specification", "specRef");
-        const filters = [];
-        const params = [];
-        if (options.projectId) {
-            params.push(options.projectId);
-            filters.push(`t."projectId" = $${params.length}`);
-        }
-        if (options.specId) {
-            params.push(options.specId);
-            filters.push(`t."specificationId" = $${params.length}`);
-        }
-        const whereClause = filters.length > 0 ? `WHERE ${filters.join(" AND ")}` : "";
-        const taskSpecVersionExpr = hasTaskSpecVersion
-            ? `t."specVersion"`
-            : `NULL::text`;
-        const taskSpecRefExpr = hasTaskSpecRef ? `t."specRef"` : `NULL::text`;
-        const currentSpecVersionExpr = hasSpecVersion
-            ? `s."version"`
-            : `NULL::text`;
-        const currentSpecRefExpr = hasSpecRef ? `s."specRef"` : `NULL::text`;
-        const rows = (await shared_1.AppDataSource.query(`
-        SELECT
-          t."id" AS "taskId",
-          t."title" AS "taskTitle",
-          t."specificationId" AS "specificationId",
-          s."id" AS "specId",
-          s."title" AS "specTitle",
-          ${taskSpecVersionExpr} AS "taskSpecVersion",
-          ${taskSpecRefExpr} AS "taskSpecRef",
-          ${currentSpecVersionExpr} AS "currentSpecVersion",
-          ${currentSpecRefExpr} AS "currentSpecRef"
-        FROM "task" t
-        LEFT JOIN "specification" s ON s."id" = t."specificationId"
-        ${whereClause}
-      `, params));
-        const driftItems = rows
-            .map((row) => {
-            const driftReasons = [];
-            if (!row.specId) {
-                driftReasons.push("spec_missing");
-            }
-            if (!hasTaskSpecVersion || !row.taskSpecVersion) {
-                driftReasons.push("task_spec_version_missing");
-            }
-            if (!hasTaskSpecRef || !row.taskSpecRef) {
-                driftReasons.push("task_spec_ref_missing");
-            }
-            if (!hasSpecRef) {
-                driftReasons.push("spec_ref_missing");
-            }
-            if (row.taskSpecVersion &&
-                row.currentSpecVersion &&
-                row.taskSpecVersion !== row.currentSpecVersion) {
-                driftReasons.push("spec_version_drift");
-            }
-            if (row.taskSpecRef &&
-                row.currentSpecRef &&
-                row.taskSpecRef !== row.currentSpecRef) {
-                driftReasons.push("spec_ref_drift");
-            }
-            return {
-                taskId: row.taskId,
-                taskTitle: row.taskTitle,
-                specificationId: row.specificationId,
-                specTitle: row.specTitle || "<missing specification>",
-                taskSpecVersion: row.taskSpecVersion,
-                currentSpecVersion: row.currentSpecVersion,
-                taskSpecRef: row.taskSpecRef,
-                currentSpecRef: row.currentSpecRef,
-                driftReasons,
-            };
-        })
-            .filter((item) => item.driftReasons.length > 0);
-        const summary = {
-            checkedTasks: rows.length,
-            driftedTasks: driftItems.length,
-            versionDrift: driftItems.filter((d) => d.driftReasons.includes("spec_version_drift")).length,
-            refDrift: driftItems.filter((d) => d.driftReasons.includes("spec_ref_drift")).length,
-            missingBindings: driftItems.filter((d) => d.driftReasons.includes("task_spec_ref_missing") ||
-                d.driftReasons.includes("task_spec_version_missing")).length,
-            missingSpecs: driftItems.filter((d) => d.driftReasons.includes("spec_missing")).length,
-        };
-        if (options.json) {
-            console.log(JSON.stringify({ summary, items: driftItems }, null, 2));
-        }
-        else {
-            console.log("Spec Drift Check");
-            console.log(`Checked tasks: ${summary.checkedTasks}`);
-            console.log(`Drifted tasks: ${summary.driftedTasks}`);
-            console.log(`Version drift: ${summary.versionDrift}`);
-            console.log(`Ref drift: ${summary.refDrift}`);
-            console.log(`Missing bindings: ${summary.missingBindings}`);
-            console.log(`Missing specs: ${summary.missingSpecs}`);
-            if (options.verbose && driftItems.length > 0) {
-                console.log("\nDrift items:");
-                for (const item of driftItems) {
-                    console.log(`- ${item.taskTitle} (${item.taskId})`);
-                    console.log(`  Spec: ${item.specTitle} (${item.specificationId})`);
-                    console.log(`  Version: ${item.taskSpecVersion ?? "<missing>"} -> ${item.currentSpecVersion ?? "<missing>"}`);
-                    console.log(`  Ref: ${item.taskSpecRef ?? "<missing>"} -> ${item.currentSpecRef ?? "<missing>"}`);
-                    console.log(`  Reasons: ${item.driftReasons.join(", ")}`);
-                }
-            }
-        }
-        if (driftItems.length > 0) {
-            return 2;
-        }
-        return 0;
-    }
-    finally {
-        await shared_1.AppDataSource.destroy();
-    }
-}
-if (require.main === module) {
-    void (0, cli_runtime_1.runCliMain)(main, { errorPrefix: "spec-drift-check failed" });
-}

package/dist/commands/spec/frontmatter.d.ts

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-/**
- * spec-frontmatter CLI Tool
- *
- * Parse and validate YAML frontmatter from a specification file.
- *
- * Usage: spekn spec frontmatter <spec-file-path> [OPTIONS]
- * Example: spekn spec frontmatter specs/SPECIFICATION.md
- */
-declare function main(argv?: string[]): number;
-export { main };