pm-skill 1.1.2 → 1.1.4

package/dist/linear.d.ts

@@ -34,6 +34,11 @@ export interface IssueDetail {
 }
 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 deleteIssue(client: LinearClient, id: string): Promise<void>;
+export declare function getTeamProjects(client: LinearClient, teamId: string): Promise<Array<{
+    id: string;
+    name: string;
+}>>;
 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>;

package/dist/linear.js

@@ -42,6 +42,14 @@ export async function createIssue(client, opts) {
 export async function updateIssue(client, id, input) {
     await client.updateIssue(id, input);
 }
+export async function deleteIssue(client, id) {
+    await client.deleteIssue(id);
+}
+export async function getTeamProjects(client, teamId) {
+    const team = await client.team(teamId);
+    const conn = await team.projects();
+    return conn.nodes.map((p) => ({ id: p.id, name: p.name }));
+}
 export async function getIssue(client, identifier) {
     try {
         return await client.issue(identifier);

package/dist/notion.d.ts

@@ -32,3 +32,28 @@ export declare function searchPages(client: Client, query: string): Promise<Arra
     id: string;
     title: string;
 }>>;
+/**
+ * Archive (delete) a Notion page by ID.
+ */
+export declare function deletePage(client: Client, pageId: string): Promise<void>;
+/**
+ * Extract Notion page ID from a Notion URL.
+ * Handles formats like: https://notion.so/abc123def456... or https://www.notion.so/workspace/Page-Title-abc123def456
+ */
+export declare function extractNotionPageId(url: string): string | null;
+/**
+ * Convert markdown to Notion blocks.
+ */
+export declare function mdToBlocks(markdown: string): BlockObjectRequest[];
+/**
+ * Create a Notion page from markdown content.
+ * Handles the 100-block-per-request API limit by chunking.
+ */
+export declare function createPageFromMarkdown(client: Client, parentPageId: string, title: string, markdown: string): Promise<{
+    id: string;
+    url: string;
+}>;
+/**
+ * Clear all blocks from a page, then append new markdown content.
+ */
+export declare function updatePageContent(client: Client, pageId: string, markdown: string): Promise<void>;

package/dist/notion.js

@@ -1,4 +1,5 @@
 import { Client } from "@notionhq/client";
+import { markdownToBlocks } from "@tryfabric/martian";
 // ── Client ──
 let _client = null;
 export function getNotionClient(apiKey) {
@@ -223,3 +224,77 @@ export async function searchPages(client, query) {
             "(untitled)",
     }));
 }
+// ── Page Deletion ──
+/**
+ * Archive (delete) a Notion page by ID.
+ */
+export async function deletePage(client, pageId) {
+    await client.pages.update({ page_id: pageId, archived: true });
+}
+/**
+ * Extract Notion page ID from a Notion URL.
+ * Handles formats like: https://notion.so/abc123def456... or https://www.notion.so/workspace/Page-Title-abc123def456
+ */
+export function extractNotionPageId(url) {
+    const match = url.match(/([a-f0-9]{32})(?:\?|$)/);
+    if (match) {
+        const raw = match[1];
+        // Format as UUID
+        return `${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(16, 20)}-${raw.slice(20)}`;
+    }
+    return null;
+}
+// ── Markdown Upload ──
+/**
+ * Convert markdown to Notion blocks.
+ */
+export function mdToBlocks(markdown) {
+    return markdownToBlocks(markdown);
+}
+/**
+ * Create a Notion page from markdown content.
+ * Handles the 100-block-per-request API limit by chunking.
+ */
+export async function createPageFromMarkdown(client, parentPageId, title, markdown) {
+    const blocks = mdToBlocks(markdown);
+    // First batch goes with page creation (max 100)
+    const firstBatch = blocks.slice(0, 100);
+    const rest = blocks.slice(100);
+    const response = await client.pages.create({
+        parent: { page_id: parentPageId },
+        properties: {
+            title: { title: [{ text: { content: title } }] },
+        },
+        children: firstBatch,
+    });
+    const pageId = response.id;
+    // Append remaining blocks in chunks of 100
+    for (let i = 0; i < rest.length; i += 100) {
+        await client.blocks.children.append({
+            block_id: pageId,
+            children: rest.slice(i, i + 100),
+        });
+    }
+    return {
+        id: pageId,
+        url: `https://notion.so/${pageId.replace(/-/g, "")}`,
+    };
+}
+/**
+ * Clear all blocks from a page, then append new markdown content.
+ */
+export async function updatePageContent(client, pageId, markdown) {
+    // 1. Delete existing blocks
+    const existing = await client.blocks.children.list({ block_id: pageId });
+    for (const block of existing.results) {
+        await client.blocks.delete({ block_id: block.id });
+    }
+    // 2. Append new blocks
+    const blocks = mdToBlocks(markdown);
+    for (let i = 0; i < blocks.length; i += 100) {
+        await client.blocks.children.append({
+            block_id: pageId,
+            children: blocks.slice(i, i + 100),
+        });
+    }
+}

package/dist/workflows.js

@@ -4,8 +4,8 @@ import { existsSync, copyFileSync, mkdirSync, readFileSync } from "fs";
 import { resolve, dirname } from "path";
 import { validateEnv, writeEnvFile, PKG_ROOT } from "./env.js";
 import { loadConfig, getTemplate, resolvePriority, resolveSeverity, validateDocType, validateLabel, } from "./config.js";
-import { getLinearClient, validateLinearKey, createIssue, getIssue, getIssueDetail, createRelation, createAttachment, createLabel, getTeams, getTeamStates, getTeamLabels, resolveLabels, } from "./linear.js";
-import { getNotionClient, createTemplatedPage, createDatabaseEntry, validateNotionKey, searchPages, } from "./notion.js";
+import { getLinearClient, validateLinearKey, createIssue, deleteIssue, getIssue, getIssueDetail, createRelation, createAttachment, createLabel, getTeams, getTeamStates, getTeamLabels, getTeamProjects, resolveLabels, } from "./linear.js";
+import { getNotionClient, createTemplatedPage, createDatabaseEntry, validateNotionKey, searchPages, createPageFromMarkdown, updatePageContent, deletePage, extractNotionPageId, } from "./notion.js";
 // ── Init ──
 function copyBundledFile(srcName, destPath) {
     if (existsSync(destPath)) {
@@ -69,7 +69,27 @@ async function init(args) {
             throw new Error(`Team '${teamId}' not found. Run 'npx pm-skill init --linear-key <key>' to see available teams.`);
         }
     }
-    // 3. Validate Notion key + auto-detect root page
+    // 3. Auto-detect project
+    let selectedProjectId = projectId;
+    if (!selectedProjectId) {
+        const projects = await getTeamProjects(client, selectedTeamId);
+        if (projects.length === 0) {
+            console.log("  No projects found — skipping project assignment");
+        }
+        else if (projects.length === 1) {
+            selectedProjectId = projects[0].id;
+            console.log(`  Auto-selected project: "${projects[0].name}"`);
+        }
+        else {
+            console.log(`\n  Available projects (${projects.length}):`);
+            for (const proj of projects) {
+                console.log(`    ${proj.name} | ${proj.id}`);
+            }
+            selectedProjectId = projects[0].id;
+            console.log(`  Using first project: "${projects[0].name}". Override with --project-id <id>`);
+        }
+    }
+    // 4. Validate Notion key + auto-detect root page
     let selectedNotionPage = notionPage;
     if (notionKey) {
         console.log("\n[Notion] Validating API key...");
@@ -103,8 +123,8 @@ async function init(args) {
         LINEAR_API_KEY: linearKey,
         LINEAR_DEFAULT_TEAM_ID: selectedTeamId,
     };
-    if (projectId)
-        envEntries.LINEAR_DEFAULT_PROJECT_ID = projectId;
+    if (selectedProjectId)
+        envEntries.LINEAR_DEFAULT_PROJECT_ID = selectedProjectId;
     if (notionKey)
         envEntries.NOTION_API_KEY = notionKey;
     if (selectedNotionPage)
@@ -240,6 +260,7 @@ async function startFeature(ctx, args) {
     await createAttachment(ctx.linear, issue.id, page.url, `${title} — PRD`);
     console.log(`[Link] Linear ↔ Notion linked`);
     console.log(`\n✅ Feature started: ${issue.identifier} | Notion: ${page.url}`);
+    console.log(`   Notion Page ID: ${page.id} (use with --parent for sub-docs)`);
 }
 async function reportBug(ctx, args) {
     const title = args._[0];
@@ -373,6 +394,167 @@ async function get(ctx, args) {
         }
     }
 }
+async function pushDoc(ctx, args) {
+    const identifier = args._[0];
+    const filePath = args._[1];
+    const content = args.content;
+    const title = args.title;
+    const parentPageId = args.parent;
+    if (!identifier || (!filePath && !content)) {
+        throw new Error("Usage: npx pm-skill push-doc <issue> <file.md> [--title T] [--parent P]\n" +
+            "       npx pm-skill push-doc <issue> --title T --content \"# md\" [--parent P]");
+    }
+    if (!ctx.notion) {
+        throw new Error("Notion is not configured. Run 'npx pm-skill init' with --notion-key.");
+    }
+    const targetParent = parentPageId ?? ctx.env.NOTION_ROOT_PAGE_ID;
+    if (!targetParent) {
+        throw new Error("No Notion parent page. Set NOTION_ROOT_PAGE_ID or use --parent <page-id>.");
+    }
+    // Read markdown
+    let markdown;
+    if (filePath) {
+        if (!existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        markdown = readFileSync(filePath, "utf-8");
+    }
+    else {
+        markdown = content;
+    }
+    // Determine title
+    const docTitle = title ?? (filePath ? filePath.replace(/^.*[\\/]/, "").replace(/\.md$/, "") : "Untitled");
+    // Get Linear issue for linking
+    const issue = await getIssue(ctx.linear, identifier);
+    // Create Notion page under specified parent
+    const page = await createPageFromMarkdown(ctx.notion, targetParent, docTitle, markdown);
+    console.log(`[Notion] Page created: "${docTitle}" — ${page.url}`);
+    console.log(`[Notion] Page ID: ${page.id}`);
+    // Link to Linear issue
+    await createAttachment(ctx.linear, issue.id, page.url, docTitle, "source-of-truth");
+    console.log(`[Link] Attached to ${issue.identifier}`);
+    console.log(`\n✅ Document pushed: ${issue.identifier} | ${page.url}`);
+}
+async function updateDoc(ctx, args) {
+    const pageId = args._[0];
+    const filePath = args._[1];
+    const content = args.content;
+    if (!pageId || (!filePath && !content)) {
+        throw new Error("Usage: npx pm-skill update-doc <page-id> <file.md>\n" +
+            "       npx pm-skill update-doc <page-id> --content \"# Updated...\"");
+    }
+    if (!ctx.notion) {
+        throw new Error("Notion is not configured. Run 'npx pm-skill init' with --notion-key.");
+    }
+    let markdown;
+    if (filePath) {
+        if (!existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        markdown = readFileSync(filePath, "utf-8");
+    }
+    else {
+        markdown = content;
+    }
+    await updatePageContent(ctx.notion, pageId, markdown);
+    console.log(`✅ Page updated: ${pageId}`);
+}
+async function createFolder(ctx, args) {
+    const folderName = args._[0];
+    const parentPageId = args.parent;
+    if (!folderName) {
+        throw new Error("Usage: npx pm-skill create-folder <name> [--parent <page-id>]");
+    }
+    if (!ctx.notion) {
+        throw new Error("Notion is not configured. Run 'npx pm-skill init' with --notion-key.");
+    }
+    const targetParent = parentPageId ?? ctx.env.NOTION_ROOT_PAGE_ID;
+    if (!targetParent) {
+        throw new Error("No Notion parent page. Set NOTION_ROOT_PAGE_ID or use --parent <page-id>.");
+    }
+    const response = await ctx.notion.pages.create({
+        parent: { page_id: targetParent },
+        properties: {
+            title: { title: [{ text: { content: folderName } }] },
+        },
+        children: [],
+    });
+    const pageId = response.id;
+    const url = `https://notion.so/${pageId.replace(/-/g, "")}`;
+    console.log(`✅ Folder created: "${folderName}"`);
+    console.log(`   Page ID: ${pageId}`);
+    console.log(`   URL: ${url}`);
+    console.log(`\nUse with: npx pm-skill push-doc <issue> <file> --parent ${pageId}`);
+}
+async function del(ctx, args) {
+    const identifiers = args._;
+    if (identifiers.length === 0) {
+        throw new Error("Usage: npx pm-skill delete <issue> [issue2 ...]");
+    }
+    for (const identifier of identifiers) {
+        const detail = await getIssueDetail(ctx.linear, identifier);
+        // Delete linked Notion pages
+        if (ctx.notion && detail.attachments.length > 0) {
+            for (const att of detail.attachments) {
+                if (att.url.includes("notion.so")) {
+                    const pageId = extractNotionPageId(att.url);
+                    if (pageId) {
+                        try {
+                            await deletePage(ctx.notion, pageId);
+                            console.log(`  [Notion] Deleted: ${att.title}`);
+                        }
+                        catch {
+                            console.log(`  [Notion] Could not delete: ${att.url} (may already be deleted or no access)`);
+                        }
+                    }
+                }
+            }
+        }
+        // Delete Linear issue
+        await deleteIssue(ctx.linear, detail.issue.id);
+        console.log(`✅ Deleted: ${detail.issue.identifier} (${detail.issue.title})`);
+    }
+}
+async function selectProject(args) {
+    // Load env manually — we need API key and team ID but not project ID
+    const { loadEnvFile, writeEnvFile } = await import("./env.js");
+    loadEnvFile();
+    const apiKey = process.env.LINEAR_API_KEY;
+    const teamId = process.env.LINEAR_DEFAULT_TEAM_ID;
+    if (!apiKey || !teamId) {
+        throw new Error("LINEAR_API_KEY and LINEAR_DEFAULT_TEAM_ID must be set. Run 'npx pm-skill init' first.");
+    }
+    const client = getLinearClient(apiKey);
+    const projects = await getTeamProjects(client, teamId);
+    if (projects.length === 0) {
+        console.log("No projects found for this team.");
+        return;
+    }
+    const projectIdArg = args._[0];
+    if (projectIdArg) {
+        // Direct selection by ID or name
+        const match = projects.find((p) => p.id === projectIdArg || p.name.toLowerCase() === projectIdArg.toLowerCase());
+        if (!match) {
+            console.log("Available projects:");
+            for (const p of projects) {
+                console.log(`  ${p.name} | ${p.id}`);
+            }
+            throw new Error(`Project '${projectIdArg}' not found.`);
+        }
+        writeEnvFile(process.cwd(), { LINEAR_DEFAULT_PROJECT_ID: match.id });
+        console.log(`✅ Selected project: "${match.name}" (${match.id})`);
+    }
+    else {
+        // List projects with current marker
+        const currentId = process.env.LINEAR_DEFAULT_PROJECT_ID;
+        console.log("Available projects:");
+        for (const p of projects) {
+            const marker = p.id === currentId ? " ← current" : "";
+            console.log(`  ${p.name} | ${p.id}${marker}`);
+        }
+        console.log(`\nUsage: npx pm-skill select-project "<name or id>"`);
+    }
+}
 // ── Command Registry ──
 const COMMANDS = {
     setup: (ctx, args) => setup(ctx, args),
@@ -382,12 +564,16 @@ const COMMANDS = {
     relate,
     block,
     "attach-doc": attachDoc,
+    "push-doc": pushDoc,
+    "update-doc": updateDoc,
+    "create-folder": createFolder,
+    delete: del,
     get,
 };
 // ── Main ──
 async function main() {
     const args = minimist(process.argv.slice(2), {
-        string: ["severity", "type", "url", "title", "linear-key", "notion-key", "team-id", "project-id", "notion-page"],
+        string: ["severity", "type", "url", "title", "content", "parent", "linear-key", "notion-key", "team-id", "project-id", "notion-page"],
         boolean: ["sync", "version"],
         alias: { s: "severity", t: "type" },
     });
@@ -408,6 +594,7 @@ Commands:
   init --linear-key K [--notion-key K]
                                      Initialize project (validates keys, creates .env, config.yml, SKILL.md, AGENTS.md)
   setup [--sync]                     Verify config & label matching (--sync creates missing labels)
+  select-project [name-or-id]        List or switch Linear project
   start-feature <title>              Start feature (Linear issue + Notion PRD)
   report-bug <title> [--severity S]  File bug report (severity: urgent/high/medium/low)
   add-task <parent> <title>          Add sub-task to an issue
@@ -416,17 +603,30 @@ Commands:
   attach-doc <issue> --url U --title T --type Y
                                      Attach document (type: source-of-truth/issue-tracking/domain-knowledge)
   get <issue>                        Show issue details
+  push-doc <issue> <file.md> [--title T] [--parent P]
+                                     Upload markdown to Notion + link to issue
+  push-doc <issue> --title T --content "# md" [--parent P]
+                                     Push content directly (for AI agents)
+  update-doc <page-id> <file.md>     Replace Notion page content with markdown
+  update-doc <page-id> --content "# md"
+                                     Replace content directly
+  create-folder <name> [--parent P]  Create Notion folder (returns page ID for --parent)
+  delete <issue> [issue2 ...]        Delete issue(s) + linked Notion pages
   help                               Show this help
   --version                          Show version
 
 All config is per-project (CWD). Run 'npx pm-skill init' in each project.`);
         return;
     }
-    // init runs independently — no env/config validation
+    // These commands run independently — no full env/config validation
     if (command === "init") {
         await init(args);
         return;
     }
+    if (command === "select-project") {
+        await selectProject(args);
+        return;
+    }
     const cmdFn = COMMANDS[command];
     if (!cmdFn) {
         const available = ["init", ...Object.keys(COMMANDS)].join(", ");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-skill",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Structured project management CLI — Linear + Notion integration for AI coding assistants (Claude Code, Codex)",
   "type": "module",
   "bin": {
@@ -48,14 +48,15 @@
   "dependencies": {
     "@linear/sdk": "^80",
     "@notionhq/client": "^5",
+    "@tryfabric/martian": "^1.2.4",
     "js-yaml": "^4",
     "minimist": "^1"
   },
   "devDependencies": {
-    "typescript": "^5",
-    "tsx": "^4",
     "@types/js-yaml": "^4",
     "@types/minimist": "^1",
-    "@types/node": "^22"
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
   }
 }