prd-cli 1.0.0

package/lib/commands/init.js

@@ -0,0 +1,221 @@
+/**
+ * prd init - Interactive workspace scaffolding
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const { CONFIG_FILENAME } = require('../config');
+
+/**
+ * Read a template file and replace {{placeholders}}
+ */
+function renderTemplate(templatePath, vars) {
+  let content = fs.readFileSync(templatePath, 'utf-8');
+  for (const [key, value] of Object.entries(vars)) {
+    content = content.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+  }
+  return content;
+}
+
+/**
+ * Create a .code-workspace file
+ */
+function createWorkspaceFile(workspacePath, workspaceName, projects) {
+  const folders = [
+    { name: 'product-docs', path: path.basename(workspacePath) }
+  ];
+
+  for (const [name, proj] of Object.entries(projects)) {
+    if (proj.repoPath) {
+      const relPath = path.relative(path.dirname(workspacePath), proj.repoPath);
+      folders.push({ name, path: relPath });
+    }
+  }
+
+  const workspace = {
+    folders,
+    settings: {}
+  };
+
+  const wsFilePath = path.join(
+    path.dirname(workspacePath),
+    `${workspaceName.replace(/\s+/g, '-').toLowerCase()}.code-workspace`
+  );
+
+  fs.writeFileSync(wsFilePath, JSON.stringify(workspace, null, 2) + '\n', 'utf-8');
+  return wsFilePath;
+}
+
+/**
+ * Main init command
+ */
+async function init(options = {}) {
+  const templatesDir = path.join(__dirname, '..', '..', 'templates');
+
+  console.log('\n' + chalk.bold.cyan('Welcome to Product OS Framework!'));
+  console.log(chalk.gray('Let\'s set up your product workspace.\n'));
+
+  // --- Prompts ---
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'workspaceName',
+      message: 'Workspace name:',
+      default: 'product-docs',
+      validate: (v) => v.trim().length > 0 || 'Name is required'
+    },
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'Your first project name:',
+      validate: (v) => {
+        if (!v.trim()) return 'Project name is required';
+        if (/[^a-zA-Z0-9_-]/.test(v.trim())) return 'Use only letters, numbers, hyphens, underscores';
+        return true;
+      }
+    },
+    {
+      type: 'input',
+      name: 'projectDescription',
+      message: 'Project description (optional):',
+      default: ''
+    },
+    {
+      type: 'confirm',
+      name: 'hasRepo',
+      message: 'Do you have an existing dev repo for this project?',
+      default: false
+    },
+    {
+      type: 'input',
+      name: 'repoPath',
+      message: 'Path to the dev repo:',
+      when: (a) => a.hasRepo,
+      validate: (v) => {
+        const resolved = path.resolve(v);
+        if (!fs.existsSync(resolved)) return `Path not found: ${resolved}`;
+        return true;
+      }
+    }
+  ]);
+
+  const wsName = answers.workspaceName.trim();
+  const projName = answers.projectName.trim();
+  const projDesc = answers.projectDescription.trim();
+  const repoPath = answers.repoPath ? path.resolve(answers.repoPath) : null;
+
+  // --- Determine target directory ---
+  const targetDir = path.resolve(process.cwd(), wsName);
+
+  if (fs.existsSync(targetDir)) {
+    const { overwrite } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'overwrite',
+      message: `Directory "${wsName}" already exists. Continue and add files?`,
+      default: false
+    }]);
+    if (!overwrite) {
+      console.log(chalk.yellow('\nAborted.\n'));
+      return;
+    }
+  }
+
+  console.log(chalk.gray('\nCreating workspace...\n'));
+
+  // --- Create directories ---
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.mkdirSync(path.join(targetDir, projName), { recursive: true });
+
+  // --- Create config ---
+  const projects = {};
+  projects[projName] = {
+    description: projDesc,
+    repoPath: repoPath || null
+  };
+
+  const config = {
+    name: wsName,
+    nextId: 1,
+    ignoreDirs: ['.git', 'node_modules', 'scripts', 'docs'],
+    projects,
+    processVersion: '2.0'
+  };
+
+  fs.writeFileSync(
+    path.join(targetDir, CONFIG_FILENAME),
+    JSON.stringify(config, null, 2) + '\n',
+    'utf-8'
+  );
+  console.log(chalk.green('  ✅ Created ') + chalk.white(`${wsName}/${CONFIG_FILENAME}`));
+
+  // --- Copy PROCESS.md ---
+  const processTemplate = path.join(templatesDir, 'PROCESS.md');
+  if (fs.existsSync(processTemplate)) {
+    fs.copyFileSync(processTemplate, path.join(targetDir, 'PROCESS.md'));
+  } else {
+    // Fallback: minimal PROCESS.md
+    fs.writeFileSync(path.join(targetDir, 'PROCESS.md'),
+      '# Product Development Process v2.0\n\nSee the Product OS Framework documentation for the full process.\n', 'utf-8');
+  }
+  console.log(chalk.green('  ✅ Created ') + chalk.white(`${wsName}/PROCESS.md`));
+
+  // --- Create README.md ---
+  const readmeContent = renderTemplate(path.join(templatesDir, 'README.md.tmpl'), {
+    workspaceName: wsName,
+    projectName: projName,
+    projectDescription: projDesc || 'No description yet',
+    nextId: 'US-001'
+  });
+  fs.writeFileSync(path.join(targetDir, 'README.md'), readmeContent, 'utf-8');
+  console.log(chalk.green('  ✅ Created ') + chalk.white(`${wsName}/README.md`));
+
+  // --- Create project backlog ---
+  const backlogContent = renderTemplate(path.join(templatesDir, 'backlog.md.tmpl'), {
+    projectName: projName
+  });
+  fs.writeFileSync(path.join(targetDir, projName, 'backlog.md'), backlogContent, 'utf-8');
+  console.log(chalk.green('  ✅ Created ') + chalk.white(`${wsName}/${projName}/backlog.md`));
+
+  // --- Create project RULES.md ---
+  const rulesContent = renderTemplate(path.join(templatesDir, 'RULES.md.tmpl'), {
+    projectName: projName
+  });
+  fs.writeFileSync(path.join(targetDir, projName, 'RULES.md'), rulesContent, 'utf-8');
+  console.log(chalk.green('  ✅ Created ') + chalk.white(`${wsName}/${projName}/RULES.md`));
+
+  // --- Create .code-workspace file ---
+  const wsFilePath = createWorkspaceFile(targetDir, wsName, projects);
+  console.log(chalk.green('  ✅ Created ') + chalk.white(path.basename(wsFilePath)));
+
+  // --- Create .gitignore ---
+  fs.writeFileSync(path.join(targetDir, '.gitignore'), 'node_modules/\n.DS_Store\n', 'utf-8');
+
+  // --- Done! ---
+  console.log('\n' + chalk.bold.green('🎉 Done! Your product workspace is ready.\n'));
+
+  const wsFileRelative = path.relative(process.cwd(), wsFilePath);
+
+  console.log(chalk.white.bold('Next steps:\n'));
+
+  const wsFileAbsolute = path.resolve(wsFilePath);
+
+  console.log(chalk.cyan('  1. Open in Cursor:'));
+  console.log(chalk.white(`     Open Cursor → File → Open Workspace from File`));
+  console.log(chalk.white(`     Navigate to: ${chalk.bold(wsFileAbsolute)}`));
+  console.log(chalk.gray(`     (This connects your product docs${repoPath ? ' and dev repo' : ''} in one workspace)\n`));
+
+  console.log(chalk.cyan('  2. Create your first story (in Cursor chat):'));
+  console.log(chalk.white(`     /create "feature description" @${projName}/backlog.md\n`));
+
+  console.log(chalk.cyan('  3. View dashboard (in any terminal):'));
+  console.log(chalk.white(`     cd ${wsName} && prd\n`));
+
+  if (!repoPath) {
+    console.log(chalk.gray('  ℹ️  No dev repo linked yet. When development starts, run:'));
+    console.log(chalk.gray(`     prd add-project ${projName} --link /path/to/repo\n`));
+  }
+}
+
+module.exports = { init };

package/lib/config.js

@@ -0,0 +1,93 @@
+/**
+ * Config file loader for Product OS Framework
+ * Reads .prd.config.json from the workspace root
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_FILENAME = '.prd.config.json';
+
+/**
+ * Find the workspace root by walking up from cwd looking for .prd.config.json
+ * @param {string} startDir - Directory to start searching from
+ * @returns {string|null} Path to workspace root, or null
+ */
+function findWorkspaceRoot(startDir) {
+  let dir = path.resolve(startDir || process.cwd());
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, CONFIG_FILENAME))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Load config from workspace root
+ * @param {string} workspacePath - Path to workspace (or auto-detect)
+ * @returns {Object} Config object with defaults applied
+ */
+function loadConfig(workspacePath) {
+  const root = workspacePath || findWorkspaceRoot(process.cwd());
+  if (!root) {
+    return null;
+  }
+
+  const configPath = path.join(root, CONFIG_FILENAME);
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const config = JSON.parse(raw);
+    config._root = root;
+    config._configPath = configPath;
+    return applyDefaults(config);
+  } catch (err) {
+    console.error(`Error reading ${CONFIG_FILENAME}:`, err.message);
+    return null;
+  }
+}
+
+/**
+ * Save config to workspace root
+ * @param {Object} config - Config object to save
+ */
+function saveConfig(config) {
+  const configPath = config._configPath;
+  if (!configPath) {
+    throw new Error('Cannot save config: no _configPath set');
+  }
+  const toWrite = { ...config };
+  delete toWrite._root;
+  delete toWrite._configPath;
+  fs.writeFileSync(configPath, JSON.stringify(toWrite, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Apply default values to config
+ * @param {Object} config
+ * @returns {Object}
+ */
+function applyDefaults(config) {
+  return {
+    name: config.name || 'Product Docs',
+    nextId: config.nextId || 1,
+    ignoreDirs: config.ignoreDirs || ['.git', 'node_modules', 'scripts', 'docs'],
+    projects: config.projects || {},
+    processVersion: config.processVersion || '2.0',
+    ...config
+  };
+}
+
+module.exports = {
+  CONFIG_FILENAME,
+  findWorkspaceRoot,
+  loadConfig,
+  saveConfig
+};

package/lib/parser.js

@@ -0,0 +1,154 @@
+/**
+ * Story Parser - Reusable core module
+ * Parses US-*.md files with YAML frontmatter
+ */
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+const { loadConfig } = require('./config');
+
+/**
+ * Parse a single story file
+ * @param {string} filePath - Path to US-*.md file
+ * @returns {Object} Story metadata
+ */
+function parseStory(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const { data, content: body } = matter(content);
+
+  // Extract title from first # heading
+  const titleMatch = body.match(/^#\s+(.+)$/m);
+  const title = titleMatch ? titleMatch[1] : 'Untitled';
+
+  // Normalize progress to string format "X/Y"
+  let progress = data.progress || '0/0';
+  if (typeof progress === 'number') {
+    progress = `${progress}/100`;
+  } else if (typeof progress !== 'string') {
+    progress = String(progress);
+  }
+  if (!progress.includes('/')) {
+    progress = `${progress}/100`;
+  }
+
+  return {
+    id: data.id || path.basename(filePath, '.md'),
+    title,
+    project: data.project || 'unknown',
+    status: data.status || 'backlog',
+    phase: data.phase || 'create',
+    progress,
+    priority: data.priority || 'P2',
+    assignee: data.assignee || 'unassigned',
+    blockers: Array.isArray(data.blockers) ? data.blockers : [],
+    dependencies: Array.isArray(data.dependencies) ? data.dependencies : [],
+    created: data.created || null,
+    updated: data.updated || null,
+    filePath
+  };
+}
+
+/**
+ * Scan all stories in a product-docs workspace
+ * @param {string} productDocsPath - Path to workspace root
+ * @returns {Object} { projects: [], stories: [], lastUpdated: Date }
+ */
+function scanAllStories(productDocsPath) {
+  if (!fs.existsSync(productDocsPath)) {
+    throw new Error(`Path does not exist: ${productDocsPath}`);
+  }
+
+  // Load config for ignore list, or use defaults
+  const config = loadConfig(productDocsPath);
+  const ignoreDirs = config
+    ? config.ignoreDirs
+    : ['.git', 'node_modules', 'scripts', 'cli', 'docs'];
+
+  const stories = [];
+  const projects = {};
+
+  const entries = fs.readdirSync(productDocsPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const projectName = entry.name;
+
+    // Skip ignored directories
+    if (projectName.startsWith('.') || ignoreDirs.includes(projectName)) {
+      continue;
+    }
+
+    const projectPath = path.join(productDocsPath, projectName);
+    const files = fs.readdirSync(projectPath);
+    const storyFiles = files.filter(f => /^US-\d+\.md$/.test(f));
+
+    if (storyFiles.length === 0) continue;
+
+    projects[projectName] = {
+      name: projectName,
+      path: projectPath,
+      storyCount: storyFiles.length,
+      stories: []
+    };
+
+    for (const file of storyFiles) {
+      try {
+        const story = parseStory(path.join(projectPath, file));
+        stories.push(story);
+        projects[projectName].stories.push(story);
+      } catch (err) {
+        // Silently skip unparseable files in production
+      }
+    }
+  }
+
+  return {
+    projects: Object.values(projects),
+    stories,
+    lastUpdated: new Date()
+  };
+}
+
+/**
+ * Get summary statistics
+ * @param {Array} stories
+ * @returns {Object}
+ */
+function getStats(stories) {
+  const stats = {
+    total: stories.length,
+    byStatus: {},
+    byPhase: {},
+    byPriority: {},
+    blocked: 0,
+    avgProgress: 0
+  };
+
+  let totalProgress = 0;
+
+  for (const story of stories) {
+    stats.byStatus[story.status] = (stats.byStatus[story.status] || 0) + 1;
+    stats.byPhase[story.phase] = (stats.byPhase[story.phase] || 0) + 1;
+    stats.byPriority[story.priority] = (stats.byPriority[story.priority] || 0) + 1;
+
+    if (story.blockers && story.blockers.length > 0) {
+      stats.blocked++;
+    }
+
+    const [completed, total] = story.progress.split('/').map(Number);
+    if (total > 0) {
+      totalProgress += (completed / total) * 100;
+    }
+  }
+
+  stats.avgProgress = stories.length > 0 ? Math.round(totalProgress / stories.length) : 0;
+  return stats;
+}
+
+module.exports = {
+  parseStory,
+  scanAllStories,
+  getStats
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "prd-cli",
+  "version": "1.0.0",
+  "description": "Product OS Framework - AI-native product development lifecycle for Cursor",
+  "main": "lib/parser.js",
+  "bin": {
+    "prd": "./bin/prd.js"
+  },
+  "scripts": {
+    "test": "node test/run.js",
+    "link": "npm link",
+    "unlink": "npm unlink"
+  },
+  "keywords": [
+    "product-management",
+    "prd",
+    "cursor",
+    "ai-native",
+    "developer-tools",
+    "product-development",
+    "agile",
+    "cli"
+  ],
+  "author": "Nimrod Margalit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimidev/product-OS-framework.git"
+  },
+  "homepage": "https://github.com/nimidev/product-OS-framework#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.3",
+    "commander": "^12.0.0",
+    "gray-matter": "^4.0.3",
+    "inquirer": "^8.2.6"
+  }
+}