@applica-software-guru/sdd 1.0.2 → 1.3.1

package/src/commands/init.ts

@@ -1,20 +1,20 @@
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { input, select } from '@inquirer/prompts';
-import clipboardy from 'clipboardy';
-import { existsSync, mkdirSync } from 'node:fs';
-import { resolve } from 'node:path';
-import ora from 'ora';
-import { SDD, writeConfig, runAgent } from '@applica-software-guru/sdd-core';
-import { printBanner } from '../ui/banner.js';
-import { success, info, heading } from '../ui/format.js';
-import { renderMarkdown } from '../ui/markdown.js';
-
-const START_PROMPT = `Read INSTRUCTIONS.md and the documentation in product/ and system/, then run \`sdd sync\` to start working.`;
+import { Command } from "commander";
+import chalk from "chalk";
+import { input, select } from "@inquirer/prompts";
+import clipboardy from "clipboardy";
+import { existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import ora from "ora";
+import { SDD, writeConfig, runAgent } from "@applica-software-guru/sdd-core";
+import { printBanner } from "../ui/banner.js";
+import { success, info, heading } from "../ui/format.js";
+import { renderMarkdown } from "../ui/markdown.js";
+
+const START_PROMPT = `Read .sdd/skill/sdd/SKILL.md (fallback: .claude/skills/sdd/SKILL.md) and the documentation in product/ and system/, then run \`sdd sync\` to start working.`;
 
 function buildBootstrapPrompt(description: string, auto: boolean): string {
   if (auto) {
-    return `Read INSTRUCTIONS.md first. This is a new SDD project.
+    return `Read .sdd/skill/sdd/SKILL.md first (fallback: .claude/skills/sdd/SKILL.md). This is a new SDD project.
 
 Project goal: "${description}"
 
@@ -28,10 +28,10 @@ Your task: generate the initial documentation for this project based on the desc
 - system/tech-stack.md — Technologies and frameworks
 - system/interfaces.md — API contracts
 
-Follow the file format described in INSTRUCTIONS.md for the YAML frontmatter. Do NOT write any code, only documentation. Commit all created files when done.`;
+Follow the file format described in .sdd/skill/sdd/references/file-format.md for the YAML frontmatter. Do NOT write any code, only documentation. Commit all created files when done.`;
   }
 
-  return `Read INSTRUCTIONS.md first. This is a new SDD project.
+  return `Read .sdd/skill/sdd/SKILL.md first (fallback: .claude/skills/sdd/SKILL.md). This is a new SDD project.
 
 Project goal: "${description}"
 
@@ -45,45 +45,49 @@ Your task: generate the initial documentation for this project. Ask me a few que
 - system/tech-stack.md — Technologies and frameworks
 - system/interfaces.md — API contracts
 
-Follow the file format described in INSTRUCTIONS.md for the YAML frontmatter. Do NOT write any code, only documentation.`;
+Follow the file format described in .sdd/skill/sdd/references/file-format.md for the YAML frontmatter. Do NOT write any code, only documentation.`;
 }
 
 export function registerInit(program: Command): void {
   program
-    .command('init <project-name>')
-    .description('Initialize a new SDD project')
+    .command("init <project-name>")
+    .description("Initialize a new SDD project")
     .action(async (projectName: string) => {
       printBanner();
 
       const projectDir = resolve(process.cwd(), projectName);
 
-      if (existsSync(resolve(projectDir, '.sdd'))) {
-        console.log(chalk.yellow(`\n  SDD project already initialized at ${projectName}/\n`));
+      if (existsSync(resolve(projectDir, ".sdd"))) {
+        console.log(
+          chalk.yellow(
+            `\n  SDD project already initialized at ${projectName}/\n`,
+          ),
+        );
         return;
       }
 
       const promptTheme = {
-        prefix: chalk.cyan('?'),
+        prefix: chalk.cyan("?"),
         style: { message: (text: string) => chalk.cyan.bold(text) },
       };
 
       const description = await input({
-        message: 'What should your project do?',
+        message: "What should your project do?",
         theme: promptTheme,
       });
 
       if (!description.trim()) {
-        console.log(chalk.yellow('\n  No description provided. Aborting.\n'));
+        console.log(chalk.yellow("\n  No description provided. Aborting.\n"));
         return;
       }
 
       const agentChoice = await select({
-        message: 'Which agent do you use?',
+        message: "Which agent do you use?",
         choices: [
-          { value: 'claude', name: 'Claude Code' },
-          { value: 'codex', name: 'Codex' },
-          { value: 'opencode', name: 'OpenCode' },
-          { value: 'other', name: 'Other' },
+          { value: "claude", name: "Claude Code" },
+          { value: "codex", name: "Codex" },
+          { value: "opencode", name: "OpenCode" },
+          { value: "other", name: "Other" },
         ],
         theme: promptTheme,
       });
@@ -91,23 +95,26 @@ export function registerInit(program: Command): void {
       let agentName = agentChoice;
       let customCommand: string | undefined;
 
-      if (agentChoice === 'other') {
+      if (agentChoice === "other") {
         agentName = await input({
-          message: 'Agent name:',
+          message: "Agent name:",
           theme: promptTheme,
         });
         customCommand = await input({
-          message: 'Agent command (use $PROMPT_FILE for the prompt file path):',
+          message: "Agent command (use $PROMPT_FILE for the prompt file path):",
           theme: promptTheme,
         });
       }
 
       const bootstrapMode = await select({
-        message: 'How do you want to start?',
+        message: "How do you want to start?",
         choices: [
-          { value: 'skip', name: 'Write docs manually' },
-          { value: 'prompt', name: 'Generate bootstrap prompt (copy to clipboard)' },
-          { value: 'auto', name: 'Generate and apply bootstrap automatically' },
+          { value: "skip", name: "Write docs manually" },
+          {
+            value: "prompt",
+            name: "Generate bootstrap prompt (copy to clipboard)",
+          },
+          { value: "auto", name: "Generate and apply bootstrap automatically" },
         ],
         theme: promptTheme,
       });
@@ -117,8 +124,8 @@ export function registerInit(program: Command): void {
       }
 
       const spinner = ora({
-        text: 'Creating project structure...',
-        color: 'cyan',
+        text: "Creating project structure...",
+        color: "cyan",
       }).start();
 
       const sdd = new SDD({ root: projectDir });
@@ -135,28 +142,31 @@ export function registerInit(program: Command): void {
       spinner.stop();
 
       // Project created
-      console.log(chalk.cyan.bold(`\n  ${chalk.white(projectName)} is ready!\n`));
+      console.log(
+        chalk.cyan.bold(`\n  ${chalk.white(projectName)} is ready!\n`),
+      );
 
       // Show what was created
-      console.log(chalk.dim('  Created:'));
+      console.log(chalk.dim("  Created:"));
       for (const f of files) {
         console.log(success(f));
       }
-      console.log(success('product/'));
-      console.log(success('product/features/'));
-      console.log(success('system/'));
-      console.log(success('code/'));
+      console.log(success("product/"));
+      console.log(success("product/features/"));
+      console.log(success("system/"));
+      console.log(success("code/"));
+      console.log(success(".claude/skills/"));
 
-      if (bootstrapMode === 'auto') {
+      if (bootstrapMode === "auto") {
         const prompt = buildBootstrapPrompt(description.trim(), true);
 
-        console.log(chalk.dim('  ─'.repeat(30)));
-        console.log(heading('Agent Prompt'));
+        console.log(chalk.dim("  ─".repeat(30)));
+        console.log(heading("Agent Prompt"));
         console.log(renderMarkdown(prompt));
-        console.log(chalk.dim('  ─'.repeat(30)));
+        console.log(chalk.dim("  ─".repeat(30)));
 
         console.log(info(`Using agent: ${chalk.cyan(agentName)}`));
-        console.log(info('Starting agent...\n'));
+        console.log(info("Starting agent...\n"));
 
         const exitCode = await runAgent({
           root: projectDir,
@@ -170,48 +180,62 @@ export function registerInit(program: Command): void {
           process.exit(exitCode);
         }
 
-        console.log(chalk.green('\n  Agent completed successfully.'));
+        console.log(chalk.green("\n  Agent completed successfully."));
         return;
       }
 
-      if (bootstrapMode === 'prompt') {
+      if (bootstrapMode === "prompt") {
         const prompt = buildBootstrapPrompt(description.trim(), false);
 
-        console.log(chalk.cyan.bold('\n  Next steps:\n'));
-        console.log(`  ${chalk.white('1.')} Enter the project folder:\n`);
+        console.log(chalk.cyan.bold("\n  Next steps:\n"));
+        console.log(`  ${chalk.white("1.")} Enter the project folder:\n`);
         console.log(`     ${chalk.green(`cd ${projectName}`)}\n`);
-        console.log(`  ${chalk.white('2.')} Open your AI agent and paste the prompt below.`);
-        console.log(`     It will ask you a few questions and generate the initial docs.\n`);
-
-        console.log(chalk.dim('  ─'.repeat(30)));
-        console.log(heading('Agent Prompt'));
+        console.log(
+          `  ${chalk.white("2.")} Open your AI agent and paste the prompt below.`,
+        );
+        console.log(
+          `     It will ask you a few questions and generate the initial docs.\n`,
+        );
+
+        console.log(chalk.dim("  ─".repeat(30)));
+        console.log(heading("Agent Prompt"));
         console.log(renderMarkdown(prompt));
 
         try {
           await clipboardy.write(prompt);
-          console.log(success('Copied to clipboard — paste it into your agent.\n'));
+          console.log(
+            success("Copied to clipboard — paste it into your agent.\n"),
+          );
         } catch {
-          console.log(info('Copy the prompt above into your agent.\n'));
+          console.log(info("Copy the prompt above into your agent.\n"));
         }
         return;
       }
 
       // skip — manual mode
-      console.log(chalk.cyan.bold('\n  Next steps:\n'));
-      console.log(`  ${chalk.white('1.')} Enter the project folder:\n`);
+      console.log(chalk.cyan.bold("\n  Next steps:\n"));
+      console.log(`  ${chalk.white("1.")} Enter the project folder:\n`);
       console.log(`     ${chalk.green(`cd ${projectName}`)}\n`);
-      console.log(`  ${chalk.white('2.')} Start writing your documentation in ${chalk.cyan('product/')} and ${chalk.cyan('system/')}.`);
-      console.log(`     Check ${chalk.cyan('INSTRUCTIONS.md')} for the file format.\n`);
-      console.log(`  ${chalk.white('3.')} When ready, let your AI agent run:\n`);
-      console.log(`     ${chalk.green('sdd sync')}\n`);
+      console.log(
+        `  ${chalk.white("2.")} Start writing your documentation in ${chalk.cyan("product/")} and ${chalk.cyan("system/")}.`,
+      );
+      console.log(
+        `     Check ${chalk.cyan(".sdd/skill/sdd/SKILL.md")} for the workflow.\n`,
+      );
+      console.log(
+        `  ${chalk.white("3.")} When ready, let your AI agent run:\n`,
+      );
+      console.log(`     ${chalk.green("sdd sync")}\n`);
 
       const prompt = START_PROMPT;
 
       try {
         await clipboardy.write(prompt);
-        console.log(success('Copied to clipboard — paste it into your agent.\n'));
+        console.log(
+          success("Copied to clipboard — paste it into your agent.\n"),
+        );
       } catch {
-        console.log(info('Copy the prompt above into your agent.\n'));
+        console.log(info("Copy the prompt above into your agent.\n"));
       }
     });
 }

package/src/commands/ui.ts

@@ -0,0 +1,161 @@
+import { Command } from 'commander';
+import { createRequire } from 'node:module';
+import { dirname, resolve, join, basename } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+import { success, info, error as fmtError } from '../ui/format.js';
+
+const SCAFFOLD_TEMPLATE = (name: string) => `import React from 'react';
+
+export default function ${name}() {
+  return (
+    <div style={{ padding: '2rem', fontFamily: 'system-ui, sans-serif' }}>
+      <h1>${name}</h1>
+      <p>Start editing this component to see changes live.</p>
+    </div>
+  );
+}
+`;
+
+const PID_FILE = '.sdd/ui.pid';
+
+function collect(value: string, prev: string[]): string[] {
+  return [...prev, value];
+}
+
+function resolveSddUiDir(): string {
+  const pkgRequire = createRequire(__filename);
+  try {
+    return dirname(pkgRequire.resolve('@applica-software-guru/sdd-ui/package.json'));
+  } catch {
+    console.error(fmtError(
+      'Package @applica-software-guru/sdd-ui not found.\n' +
+      '  Run: npm install @applica-software-guru/sdd-ui',
+    ));
+    process.exit(1);
+  }
+}
+
+export function registerUI(program: Command): void {
+  const ui = program
+    .command('ui')
+    .description('UI Component Editor — visual development with live preview');
+
+  // launch-editor
+  ui
+    .command('launch-editor <component-name>')
+    .description('Launch the split-panel UI editor for a React component')
+    .option('--screenshot <path>', 'Screenshot to show in the spec panel (repeatable)', collect, [])
+    .option('--port <n>', 'Port for the UI editor', '5174')
+    .option('--detach', 'Run in background and return immediately')
+    .action(async (componentName: string, options) => {
+      const projectRoot = process.cwd();
+      const port = options.port as string;
+      const detach = Boolean(options.detach);
+      const screenshotArgs = options.screenshot as string[];
+
+      // Resolve and validate screenshot paths
+      const screenshotPaths = screenshotArgs.map((p) => resolve(projectRoot, p));
+      for (const p of screenshotPaths) {
+        if (!existsSync(p)) {
+          console.error(fmtError(`Screenshot not found: ${p}`));
+          process.exit(1);
+        }
+      }
+
+      // Resolve component path
+      const componentsDir = join(projectRoot, 'code', 'components');
+      const componentPath = join(componentsDir, `${componentName}.tsx`);
+
+      // Scaffold component if it doesn't exist
+      if (!existsSync(componentPath)) {
+        if (!existsSync(componentsDir)) {
+          mkdirSync(componentsDir, { recursive: true });
+        }
+        writeFileSync(componentPath, SCAFFOLD_TEMPLATE(componentName), 'utf-8');
+        console.log(info(`Scaffolded component at ${chalk.cyan(componentPath)}`));
+      }
+
+      const sddUiDir = resolveSddUiDir();
+
+      // Write .env.local — screenshot paths are pipe-separated (| is not valid in fs paths)
+      const envLines = [
+        `VITE_COMPONENT_PATH=${componentPath}`,
+        `VITE_COMPONENT_NAME=${componentName}`,
+        `VITE_SCREENSHOT_PATHS=${screenshotPaths.join('|')}`,
+      ];
+      await writeFile(join(sddUiDir, '.env.local'), envLines.join('\n'), 'utf-8');
+
+      // Print launch info
+      console.log('');
+      console.log(success(`sdd-ui starting on ${chalk.cyan(`http://localhost:${port}`)}`));
+      console.log(info(`Component:  ${chalk.cyan(componentPath)}`));
+      for (const p of screenshotPaths) {
+        console.log(info(`Screenshot: ${chalk.cyan(basename(p))}  ${chalk.dim(p)}`));
+      }
+
+      if (detach) {
+        // Launch detached — process survives after sdd exits
+        const vite = spawn('npx', ['vite', '--port', port], {
+          cwd: sddUiDir,
+          stdio: 'ignore',
+          detached: true,
+          shell: false,
+        });
+        vite.unref();
+
+        // Save PID so `sdd ui stop` can kill it
+        const pidFile = join(projectRoot, PID_FILE);
+        writeFileSync(pidFile, String(vite.pid), 'utf-8');
+
+        console.log(info(`Running in background  ${chalk.dim(`(PID ${vite.pid})`)}`));
+        console.log(chalk.dim(`  Stop with: ${chalk.white('sdd ui stop')}\n`));
+      } else {
+        console.log(chalk.dim('  Press Ctrl+C to stop.\n'));
+
+        const vite = spawn('npx', ['vite', '--port', port], {
+          cwd: sddUiDir,
+          stdio: 'inherit',
+          shell: false,
+        });
+
+        vite.on('error', (err) => {
+          console.error(fmtError(`Failed to start vite: ${err.message}`));
+          process.exit(1);
+        });
+
+        vite.on('close', (code) => process.exit(code ?? 0));
+
+        process.on('SIGINT', () => vite.kill('SIGINT'));
+        process.on('SIGTERM', () => vite.kill('SIGTERM'));
+      }
+    });
+
+  // stop
+  ui
+    .command('stop')
+    .description('Stop a detached UI editor started with --detach')
+    .action(() => {
+      const projectRoot = process.cwd();
+      const pidFile = join(projectRoot, PID_FILE);
+
+      if (!existsSync(pidFile)) {
+        console.log(info('No running sdd-ui process found.'));
+        return;
+      }
+
+      const pid = parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
+
+      try {
+        process.kill(pid, 'SIGTERM');
+        unlinkSync(pidFile);
+        console.log(success(`Stopped sdd-ui  ${chalk.dim(`(PID ${pid})`)}`));
+      } catch {
+        // Process already dead — clean up the stale pid file
+        unlinkSync(pidFile);
+        console.log(info('Process was already stopped. Cleaned up pid file.'));
+      }
+    });
+}

package/src/commands/upgrade.ts

@@ -0,0 +1,51 @@
+import { Command } from 'commander';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+import { heading, success, info } from '../ui/format.js';
+import { installSkills } from '../skills.js';
+
+export function registerUpgrade(program: Command): void {
+  program
+    .command('upgrade')
+    .description('Upgrade sdd to the latest version and refresh skills in the current project')
+    .action(async () => {
+      console.log(heading('SDD Upgrade'));
+      console.log(info('Running: npm install -g @applica-software-guru/sdd@latest\n'));
+
+      const exitCode = await new Promise<number>((resolve) => {
+        const child = spawn('npm', ['install', '-g', '@applica-software-guru/sdd@latest'], {
+          stdio: 'inherit',
+          shell: false,
+        });
+        child.on('close', (code) => resolve(code ?? 1));
+        child.on('error', () => resolve(1));
+      });
+
+      if (exitCode !== 0) {
+        console.error(chalk.red('\n  Upgrade failed. Check the output above.'));
+        process.exit(exitCode);
+      }
+
+      console.log('');
+      console.log(success('CLI upgraded.'));
+
+      // If run from inside an SDD project, refresh the skills too
+      const projectRoot = process.cwd();
+      const isSddProject = existsSync(join(projectRoot, '.sdd', 'config.yaml'));
+
+      if (isSddProject) {
+        const updated = installSkills(projectRoot);
+        if (updated) {
+          console.log(success(`Skills updated in ${chalk.cyan('.claude/skills/')}`));
+        }
+      } else {
+        console.log(
+          chalk.dim(
+            '\n  Run this command from inside an SDD project to also refresh skill files.',
+          ),
+        );
+      }
+    });
+}

package/src/index.ts

@@ -1,21 +1,28 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
-import { registerInit } from './commands/init.js';
-import { registerStatus } from './commands/status.js';
-import { registerDiff } from './commands/diff.js';
-import { registerSync } from './commands/sync.js';
-import { registerValidate } from './commands/validate.js';
-import { registerMarkSynced } from './commands/mark-synced.js';
-import { registerCR } from './commands/cr.js';
-import { registerBug } from './commands/bug.js';
-import { registerApply } from './commands/apply.js';
+import { Command } from "commander";
+import { createRequire } from "node:module";
+import { registerInit } from "./commands/init.js";
+import { registerStatus } from "./commands/status.js";
+import { registerDiff } from "./commands/diff.js";
+import { registerSync } from "./commands/sync.js";
+import { registerValidate } from "./commands/validate.js";
+import { registerMarkSynced } from "./commands/mark-synced.js";
+import { registerCR } from "./commands/cr.js";
+import { registerBug } from "./commands/bug.js";
+import { registerApply } from "./commands/apply.js";
+import { registerAdapters } from "./commands/adapters.js";
+import { registerUI } from "./commands/ui.js";
+import { registerUpgrade } from "./commands/upgrade.js";
+
+const packageRequire = createRequire(__filename);
+const packageJson = packageRequire("../package.json") as { version: string };
 
 const program = new Command();
 
 program
-  .name('sdd')
-  .description('Story Driven Development — manage apps through structured documentation')
-  .version('1.0.1');
+  .name("sdd")
+  .description("Story Driven Development — manage apps through structured documentation")
+  .version(packageJson.version);
 
 registerInit(program);
 registerStatus(program);
@@ -26,6 +33,9 @@ registerMarkSynced(program);
 registerCR(program);
 registerBug(program);
 registerApply(program);
+registerAdapters(program);
+registerUI(program);
+registerUpgrade(program);
 
 program.parseAsync().catch((err) => {
   console.error(err.message);

package/src/skills.ts

@@ -0,0 +1,25 @@
+import { cpSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/**
+ * Returns the path to the bundled skills directory inside the CLI package.
+ * Works both in development (monorepo) and when installed globally.
+ */
+export function getSkillsSourceDir(): string {
+  // __filename → <cli-pkg>/dist/skills.js → go up two levels to <cli-pkg>/
+  const cliPkgDir = resolve(dirname(__filename), '..');
+  return join(cliPkgDir, 'skills');
+}
+
+/**
+ * Copies all bundled skill files into <projectDir>/.claude/skills/.
+ * Safe to call on existing projects — overwrites with the latest version.
+ */
+export function installSkills(projectDir: string): boolean {
+  const src = getSkillsSourceDir();
+  if (!existsSync(src)) return false;
+
+  const dest = join(projectDir, '.claude', 'skills');
+  cpSync(src, dest, { recursive: true, force: true });
+  return true;
+}