pm-skill 1.0.0

package/dist/env.js

@@ -0,0 +1,153 @@
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from "fs";
+import { homedir } from "os";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, "..");
+export const GLOBAL_DIR = resolve(homedir(), ".pm-skill");
+/**
+ * Resolve a file by checking multiple directories in order:
+ * 1. CWD (project-local override)
+ * 2. ~/.pm-skill/ (user-global config)
+ * 3. Package root (bundled defaults)
+ */
+export function resolveFile(filename) {
+    const candidates = [
+        resolve(process.cwd(), filename),
+        resolve(GLOBAL_DIR, filename),
+        resolve(PKG_ROOT, filename),
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+const REQUIRED_KEYS = ["LINEAR_API_KEY", "LINEAR_DEFAULT_TEAM_ID"];
+const NOTION_KEYS = ["NOTION_API_KEY", "NOTION_ROOT_PAGE_ID"];
+const KEY_HELP = {
+    LINEAR_API_KEY: "Linear > Settings > API > Personal API Keys",
+    LINEAR_DEFAULT_TEAM_ID: "'pm-skill init' or 'pm-skill setup' to discover your team ID",
+    LINEAR_DEFAULT_PROJECT_ID: "Linear > Project Settings (optional)",
+    NOTION_API_KEY: "https://www.notion.so/my-integrations",
+    NOTION_ROOT_PAGE_ID: "Parent page ID where Notion docs will be created",
+    NOTION_BUG_DB_ID: "Notion DB ID for bug tracking (optional — falls back to page creation)",
+};
+/**
+ * Parse a single .env file and set values into process.env.
+ * Does NOT overwrite existing values (earlier loads take precedence).
+ */
+function parseEnvFile(filePath) {
+    const content = readFileSync(filePath, "utf-8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx === -1)
+            continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        const val = trimmed.slice(eqIdx + 1).trim();
+        if (!process.env[key]) {
+            process.env[key] = val;
+        }
+    }
+}
+/**
+ * Hierarchical .env loading:
+ * 1. CWD/.env (project-specific, highest priority)
+ * 2. ~/.pm-skill/.env (global defaults, fills in missing keys)
+ *
+ * Both files are loaded. CWD values take precedence over global.
+ */
+export function loadEnvFiles() {
+    const cwdEnv = resolve(process.cwd(), ".env");
+    const globalEnv = resolve(GLOBAL_DIR, ".env");
+    // CWD first — these values win
+    if (existsSync(cwdEnv))
+        parseEnvFile(cwdEnv);
+    // Global second — fills in anything CWD didn't set
+    if (existsSync(globalEnv))
+        parseEnvFile(globalEnv);
+}
+export function validateEnv(command) {
+    loadEnvFiles();
+    const missing = [];
+    if (command === "setup" || command === "init") {
+        if (!process.env.LINEAR_API_KEY) {
+            missing.push("LINEAR_API_KEY");
+        }
+    }
+    else {
+        for (const key of REQUIRED_KEYS) {
+            if (!process.env[key])
+                missing.push(key);
+        }
+    }
+    const notionCommands = ["start-feature", "report-bug"];
+    if (notionCommands.includes(command)) {
+        for (const key of NOTION_KEYS) {
+            if (!process.env[key])
+                missing.push(key);
+        }
+    }
+    if (missing.length > 0) {
+        const hints = missing
+            .map((k) => `  ${k}: ${KEY_HELP[k] ?? ""}`)
+            .join("\n");
+        throw new Error(`Required environment variables are not set:\n${hints}\n\n` +
+            `Run 'pm-skill init' to set up, or create .env manually.\n` +
+            `Config lookup: CWD/.env → ~/.pm-skill/.env (both loaded, CWD wins).`);
+    }
+    return {
+        LINEAR_API_KEY: process.env.LINEAR_API_KEY,
+        LINEAR_DEFAULT_TEAM_ID: process.env.LINEAR_DEFAULT_TEAM_ID,
+        LINEAR_DEFAULT_PROJECT_ID: process.env.LINEAR_DEFAULT_PROJECT_ID,
+        NOTION_API_KEY: process.env.NOTION_API_KEY,
+        NOTION_ROOT_PAGE_ID: process.env.NOTION_ROOT_PAGE_ID,
+        NOTION_BUG_DB_ID: process.env.NOTION_BUG_DB_ID,
+    };
+}
+/**
+ * Write key=value pairs to a .env file.
+ * If the file exists, updates existing keys and appends new ones.
+ * If not, creates it fresh.
+ */
+export function writeEnvFile(targetDir, entries) {
+    mkdirSync(targetDir, { recursive: true });
+    const envPath = resolve(targetDir, ".env");
+    const existing = new Map();
+    const lines = [];
+    if (existsSync(envPath)) {
+        const content = readFileSync(envPath, "utf-8");
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#")) {
+                lines.push(line);
+                continue;
+            }
+            const eqIdx = trimmed.indexOf("=");
+            if (eqIdx === -1) {
+                lines.push(line);
+                continue;
+            }
+            const key = trimmed.slice(0, eqIdx).trim();
+            existing.set(key, trimmed);
+            // Will be replaced or kept
+            if (key in entries) {
+                lines.push(`${key}=${entries[key]}`);
+            }
+            else {
+                lines.push(line);
+            }
+        }
+    }
+    // Append new keys not already in file
+    for (const [key, val] of Object.entries(entries)) {
+        if (!existing.has(key)) {
+            lines.push(`${key}=${val}`);
+        }
+    }
+    writeFileSync(envPath, lines.join("\n") + "\n", "utf-8");
+    return envPath;
+}

package/dist/linear.d.ts

@@ -0,0 +1,48 @@
+import { LinearClient, type Issue, type IssueLabel, type WorkflowState, type Team } from "@linear/sdk";
+export declare function getLinearClient(apiKey: string): LinearClient;
+/**
+ * Validate a Linear API key by calling viewer endpoint.
+ * Returns user info on success, throws on failure.
+ */
+export declare function validateLinearKey(apiKey: string): Promise<{
+    id: string;
+    name: string;
+    email: string;
+}>;
+export interface CreateIssueOpts {
+    teamId: string;
+    title: string;
+    description?: string;
+    priority?: number;
+    labelIds?: string[];
+    parentId?: string;
+    projectId?: string;
+    stateId?: string;
+}
+export interface IssueDetail {
+    issue: Issue;
+    children: Issue[];
+    relations: Array<{
+        type: string;
+        issue: Issue;
+    }>;
+    attachments: Array<{
+        title: string;
+        url: string;
+        subtitle?: string | null;
+    }>;
+}
+export declare function createIssue(client: LinearClient, opts: CreateIssueOpts): Promise<Issue>;
+export declare function updateIssue(client: LinearClient, id: string, input: Record<string, unknown>): Promise<void>;
+export declare function getIssue(client: LinearClient, identifier: string): Promise<Issue>;
+export declare function getIssueDetail(client: LinearClient, identifier: string): Promise<IssueDetail>;
+export declare function createRelation(client: LinearClient, issueId: string, relatedIssueId: string, type: "blocks" | "related" | "similar"): Promise<void>;
+export declare function createAttachment(client: LinearClient, issueId: string, url: string, title: string, subtitle?: string): Promise<void>;
+export declare function getTeams(client: LinearClient): Promise<Team[]>;
+export declare function getTeamStates(client: LinearClient, teamId: string): Promise<WorkflowState[]>;
+export declare function getTeamLabels(client: LinearClient, teamId: string): Promise<IssueLabel[]>;
+/**
+ * config의 label name으로 Linear 워크스페이스 라벨 ID를 매칭합니다.
+ * 대소문자 무시 매칭. 미매칭 시 에러.
+ */
+export declare function resolveLabels(configLabelNames: string[], teamLabels: IssueLabel[]): string[];

package/dist/linear.js

@@ -0,0 +1,138 @@
+import { LinearClient, IssueRelationType } from "@linear/sdk";
+// ── Client ──
+let _client = null;
+export function getLinearClient(apiKey) {
+    if (!_client) {
+        _client = new LinearClient({ apiKey });
+    }
+    return _client;
+}
+/**
+ * Validate a Linear API key by calling viewer endpoint.
+ * Returns user info on success, throws on failure.
+ */
+export async function validateLinearKey(apiKey) {
+    const client = new LinearClient({ apiKey });
+    try {
+        const viewer = await client.viewer;
+        return { id: viewer.id, name: viewer.name, email: viewer.email };
+    }
+    catch {
+        throw new Error("Linear API key validation failed. Check your key at: Linear > Settings > API > Personal API Keys");
+    }
+}
+// ── Issue CRUD ──
+export async function createIssue(client, opts) {
+    const payload = await client.createIssue({
+        teamId: opts.teamId,
+        title: opts.title,
+        description: opts.description,
+        priority: opts.priority,
+        labelIds: opts.labelIds,
+        parentId: opts.parentId,
+        projectId: opts.projectId,
+        stateId: opts.stateId,
+    });
+    const issue = await payload.issue;
+    if (!issue) {
+        throw new Error("이슈 생성에 실패했습니다.");
+    }
+    return issue;
+}
+export async function updateIssue(client, id, input) {
+    await client.updateIssue(id, input);
+}
+export async function getIssue(client, identifier) {
+    try {
+        return await client.issue(identifier);
+    }
+    catch {
+        throw new Error(`이슈 '${identifier}'을 찾을 수 없습니다.`);
+    }
+}
+export async function getIssueDetail(client, identifier) {
+    const issue = await getIssue(client, identifier);
+    const [childrenConn, relationsConn, attachmentsConn] = await Promise.all([
+        issue.children(),
+        issue.relations(),
+        issue.attachments(),
+    ]);
+    const relations = [];
+    for (const rel of relationsConn.nodes) {
+        const relatedIssue = await rel.relatedIssue;
+        if (relatedIssue) {
+            relations.push({ type: rel.type, issue: relatedIssue });
+        }
+    }
+    return {
+        issue,
+        children: childrenConn.nodes,
+        relations,
+        attachments: attachmentsConn.nodes.map((a) => ({
+            title: a.title,
+            url: a.url,
+            subtitle: a.subtitle,
+        })),
+    };
+}
+// ── Relations ──
+const RELATION_TYPE_MAP = {
+    blocks: IssueRelationType.Blocks,
+    related: IssueRelationType.Related,
+    similar: IssueRelationType.Similar,
+    duplicate: IssueRelationType.Duplicate,
+};
+export async function createRelation(client, issueId, relatedIssueId, type) {
+    const relationType = RELATION_TYPE_MAP[type];
+    if (!relationType) {
+        throw new Error(`알 수 없는 관계 유형: '${type}'`);
+    }
+    await client.createIssueRelation({
+        issueId,
+        relatedIssueId,
+        type: relationType,
+    });
+}
+// ── Attachments ──
+export async function createAttachment(client, issueId, url, title, subtitle) {
+    await client.createAttachment({
+        issueId,
+        url,
+        title,
+        subtitle,
+    });
+}
+// ── Team / Labels / States ──
+export async function getTeams(client) {
+    const conn = await client.teams();
+    return conn.nodes;
+}
+export async function getTeamStates(client, teamId) {
+    const team = await client.team(teamId);
+    const conn = await team.states();
+    return conn.nodes;
+}
+export async function getTeamLabels(client, teamId) {
+    const team = await client.team(teamId);
+    const conn = await team.labels();
+    return conn.nodes;
+}
+/**
+ * config의 label name으로 Linear 워크스페이스 라벨 ID를 매칭합니다.
+ * 대소문자 무시 매칭. 미매칭 시 에러.
+ */
+export function resolveLabels(configLabelNames, teamLabels) {
+    const ids = [];
+    const labelMap = new Map(teamLabels.map((l) => [l.name.toLowerCase(), l.id]));
+    for (const name of configLabelNames) {
+        const id = labelMap.get(name.toLowerCase());
+        if (!id) {
+            const available = teamLabels.map((l) => l.name).join(", ");
+            throw new Error(`Linear 워크스페이스에서 라벨 '${name}'을 찾을 수 없습니다.\n` +
+                `사용 가능한 라벨: ${available}\n` +
+                `'setup' 커맨드로 라벨 매칭 상태를 확인하세요.`);
+        }
+        ids.push(id);
+    }
+    return ids;
+}

package/dist/notion.d.ts

@@ -0,0 +1,34 @@
+import { Client } from "@notionhq/client";
+import type { BlockObjectRequest } from "@notionhq/client/build/src/api-endpoints.js";
+export declare function getNotionClient(apiKey: string): Client;
+/**
+ * Validate a Notion API key by calling users.me endpoint.
+ * Returns bot info on success, throws on failure.
+ */
+export declare function validateNotionKey(apiKey: string): Promise<{
+    id: string;
+    name: string;
+}>;
+export declare function buildFeaturePRD(title: string, linearUrl: string): BlockObjectRequest[];
+export declare function buildBugReport(title: string, severity: string, linearUrl: string): BlockObjectRequest[];
+export declare function buildDesignDoc(title: string, linearUrl: string): BlockObjectRequest[];
+export declare function buildImprovement(title: string, linearUrl: string): BlockObjectRequest[];
+export declare function buildRefactor(title: string, linearUrl: string): BlockObjectRequest[];
+export declare function getTemplateBlocks(notionTemplate: string, title: string, linearUrl: string, severity?: string): BlockObjectRequest[];
+export declare function createPage(client: Client, parentPageId: string, title: string, blocks: BlockObjectRequest[]): Promise<{
+    id: string;
+    url: string;
+}>;
+export declare function createDatabaseEntry(client: Client, databaseId: string, properties: Record<string, unknown>): Promise<{
+    id: string;
+    url: string;
+}>;
+export declare function createTemplatedPage(client: Client, parentPageId: string, notionTemplate: string, title: string, linearUrl: string, severity?: string): Promise<{
+    id: string;
+    url: string;
+}>;
+export declare function getPage(client: Client, pageId: string): Promise<Record<string, unknown>>;
+export declare function searchPages(client: Client, query: string): Promise<Array<{
+    id: string;
+    title: string;
+}>>;

package/dist/notion.js

@@ -0,0 +1,225 @@
+import { Client } from "@notionhq/client";
+// ── Client ──
+let _client = null;
+export function getNotionClient(apiKey) {
+    if (!_client) {
+        _client = new Client({ auth: apiKey });
+    }
+    return _client;
+}
+/**
+ * Validate a Notion API key by calling users.me endpoint.
+ * Returns bot info on success, throws on failure.
+ */
+export async function validateNotionKey(apiKey) {
+    const client = new Client({ auth: apiKey });
+    try {
+        const me = await client.users.me({});
+        return { id: me.id, name: me.name ?? "(unnamed integration)" };
+    }
+    catch {
+        throw new Error("Notion API key validation failed. Check your key at: https://www.notion.so/my-integrations");
+    }
+}
+// ── Block Builders ──
+function text(content) {
+    return [{ type: "text", text: { content } }];
+}
+function heading1(content) {
+    return {
+        object: "block",
+        type: "heading_1",
+        heading_1: { rich_text: text(content) },
+    };
+}
+function heading2(content) {
+    return {
+        object: "block",
+        type: "heading_2",
+        heading_2: { rich_text: text(content) },
+    };
+}
+function paragraph(content) {
+    return {
+        object: "block",
+        type: "paragraph",
+        paragraph: { rich_text: text(content) },
+    };
+}
+function todo(content, checked = false) {
+    return {
+        object: "block",
+        type: "to_do",
+        to_do: { rich_text: text(content), checked },
+    };
+}
+function numberedItem(content) {
+    return {
+        object: "block",
+        type: "numbered_list_item",
+        numbered_list_item: { rich_text: text(content) },
+    };
+}
+function bookmark(url) {
+    return {
+        object: "block",
+        type: "bookmark",
+        bookmark: { url },
+    };
+}
+function divider() {
+    return {
+        object: "block",
+        type: "divider",
+        divider: {},
+    };
+}
+// ── Template Builders ──
+export function buildFeaturePRD(title, linearUrl) {
+    return [
+        heading2(`📋 ${title}`),
+        bookmark(linearUrl),
+        divider(),
+        heading1("목표"),
+        paragraph(""),
+        heading1("배경"),
+        paragraph(""),
+        heading1("요구사항"),
+        todo("요구사항 1"),
+        todo("요구사항 2"),
+        todo("요구사항 3"),
+        heading1("설계"),
+        paragraph(""),
+        heading1("테스트 계획"),
+        paragraph(""),
+    ];
+}
+export function buildBugReport(title, severity, linearUrl) {
+    return [
+        heading2(`🐛 ${title} (${severity})`),
+        bookmark(linearUrl),
+        divider(),
+        heading1("재현 단계"),
+        numberedItem("단계 1"),
+        numberedItem("단계 2"),
+        numberedItem("단계 3"),
+        heading1("예상 동작"),
+        paragraph(""),
+        heading1("실제 동작"),
+        paragraph(""),
+        heading1("환경"),
+        paragraph("OS / 브라우저 / 디바이스"),
+        heading1("해결 방안"),
+        paragraph(""),
+    ];
+}
+export function buildDesignDoc(title, linearUrl) {
+    return [
+        heading2(`📐 ${title}`),
+        bookmark(linearUrl),
+        divider(),
+        heading1("개요"),
+        paragraph(""),
+        heading1("제약 조건"),
+        paragraph(""),
+        heading1("옵션 비교"),
+        paragraph(""),
+        heading1("결정"),
+        paragraph(""),
+        heading1("후속 작업"),
+        todo("후속 작업 1"),
+        todo("후속 작업 2"),
+    ];
+}
+export function buildImprovement(title, linearUrl) {
+    return [
+        heading2(`✨ ${title}`),
+        bookmark(linearUrl),
+        divider(),
+        heading1("현재 상태"),
+        paragraph(""),
+        heading1("개선 목표"),
+        paragraph(""),
+        heading1("변경 사항"),
+        todo("변경 1"),
+        todo("변경 2"),
+        todo("변경 3"),
+        heading1("영향 범위"),
+        paragraph(""),
+    ];
+}
+export function buildRefactor(title, linearUrl) {
+    return [
+        heading2(`🔧 ${title}`),
+        bookmark(linearUrl),
+        divider(),
+        heading1("리팩토링 대상"),
+        paragraph(""),
+        heading1("현재 문제점"),
+        paragraph(""),
+        heading1("변경 계획"),
+        todo("단계 1"),
+        todo("단계 2"),
+        heading1("검증 방법"),
+        paragraph(""),
+    ];
+}
+// ── Template Dispatcher ──
+const TEMPLATE_BUILDERS = {
+    "feature-prd": buildFeaturePRD,
+    "bug-report": (t, u, s) => buildBugReport(t, s ?? "medium", u),
+    "design-doc": buildDesignDoc,
+    improvement: buildImprovement,
+    refactor: buildRefactor,
+};
+export function getTemplateBlocks(notionTemplate, title, linearUrl, severity) {
+    const builder = TEMPLATE_BUILDERS[notionTemplate];
+    if (!builder) {
+        const available = Object.keys(TEMPLATE_BUILDERS).join(", ");
+        throw new Error(`notion_template '${notionTemplate}'에 대한 빌더가 없습니다.\n등록된 템플릿: ${available}`);
+    }
+    return builder(title, linearUrl, severity);
+}
+// ── Page CRUD ──
+export async function createPage(client, parentPageId, title, blocks) {
+    const response = await client.pages.create({
+        parent: { page_id: parentPageId },
+        properties: {
+            title: { title: [{ text: { content: title } }] },
+        },
+        children: blocks,
+    });
+    return {
+        id: response.id,
+        url: `https://notion.so/${response.id.replace(/-/g, "")}`,
+    };
+}
+export async function createDatabaseEntry(client, databaseId, properties) {
+    const response = await client.pages.create({
+        parent: { database_id: databaseId },
+        properties: properties,
+    });
+    return {
+        id: response.id,
+        url: `https://notion.so/${response.id.replace(/-/g, "")}`,
+    };
+}
+export async function createTemplatedPage(client, parentPageId, notionTemplate, title, linearUrl, severity) {
+    const blocks = getTemplateBlocks(notionTemplate, title, linearUrl, severity);
+    return createPage(client, parentPageId, title, blocks);
+}
+export async function getPage(client, pageId) {
+    return (await client.pages.retrieve({ page_id: pageId }));
+}
+export async function searchPages(client, query) {
+    const response = await client.search({
+        query,
+        filter: { property: "object", value: "page" },
+    });
+    return response.results.map((page) => ({
+        id: page.id,
+        title: page.properties?.title?.title?.[0]?.text?.content ??
+            page.properties?.Name?.title?.[0]?.text?.content ??
+            "(untitled)",
+    }));
+}

package/dist/workflows.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};