serpentstack 0.1.0 → 0.2.1

package/bin/serpentstack.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { error, bold, getVersion, printHeader } from '../lib/utils/ui.js';
+import { error, bold, dim, green, cyan, getVersion, printHeader } from '../lib/utils/ui.js';
 
 function parseFlags(args) {
   const flags = {};
@@ -20,22 +20,30 @@ function showHelp() {
   printHeader();
   console.log(`  ${bold('Usage:')} serpentstack <command> [options]
 
-  ${bold('Stack commands')} (new projects):
-    stack new <name>              Scaffold a new project from the template
-    stack update                  Update template-level files to latest
+  ${bold(green('Stack commands'))} ${dim('(new projects)')}
+    ${cyan('stack new')} <name>              Scaffold a new project from the template
+    ${cyan('stack update')}                  Update template-level files to latest
 
-  ${bold('Skills commands')} (any project):
-    skills init                   Download base skills + persistent agent configs
-    skills update                 Update base skills to latest versions
-    skills persistent --create    Set up OpenClaw workspace for your project
-    skills persistent --start     Install OpenClaw (if needed) and start agent
-    skills persistent --stop      Stop the background agent
+  ${bold(green('Skills commands'))} ${dim('(any project)')}
+    ${cyan('skills init')}                   Download base skills + persistent agent configs
+    ${cyan('skills update')}                 Update base skills to latest versions
+    ${cyan('skills persistent')} --create    Set up OpenClaw workspace for your project
+    ${cyan('skills persistent')} --start     Install OpenClaw (if needed) and start agent
+    ${cyan('skills persistent')} --stop      Stop the background agent
 
   ${bold('Options:')}
     --force                       Overwrite existing files
     --all                         Include new files in updates (skills update)
     --version                     Show version
     --help                        Show this help
+
+  ${dim('Examples:')}
+    ${dim('$')} serpentstack stack new my-saas-app
+    ${dim('$')} serpentstack skills init
+    ${dim('$')} serpentstack skills init --force
+    ${dim('$')} serpentstack skills persistent --start
+
+  ${dim('Docs: https://github.com/Benja-Pauls/SerpentStack')}
 `);
 }
 
@@ -85,8 +93,8 @@ async function main() {
       process.exit(1);
     }
   } else {
-    error(`Unknown command: ${noun}`);
-    showHelp();
+    error(`Unknown command: ${bold(noun)}`);
+    console.log(`\n  Run ${bold('serpentstack --help')} to see available commands.\n`);
     process.exit(1);
   }
 }

package/lib/commands/skills-init.js

@@ -1,24 +1,34 @@
 import { join } from 'node:path';
 import { downloadFile } from '../utils/github.js';
 import { safeWrite } from '../utils/fs-helpers.js';
-import { info, success, warn, error, spinner, bold, dim } from '../utils/ui.js';
+import { info, success, warn, error, spinner, bold, dim, green, printBox, printPrompt, fileStatus } from '../utils/ui.js';
 
-const MANIFEST = [
+const SKILLS_FILES = [
   '.skills/find-skills/SKILL.md',
   '.skills/generate-skills/SKILL.md',
   '.skills/git-workflow/SKILL.md',
   '.skills/model-routing/SKILL.md',
+];
+
+const OPENCLAW_FILES = [
   '.openclaw/SOUL.md',
   '.openclaw/HEARTBEAT.md',
   '.openclaw/AGENTS.md',
+];
+
+const DOCS_FILES = [
   'SKILL-AUTHORING.md',
 ];
 
+const MANIFEST = [...SKILLS_FILES, ...OPENCLAW_FILES, ...DOCS_FILES];
+
 export async function skillsInit({ force = false } = {}) {
+  console.log();
   info(`Downloading SerpentStack skills into ${bold(process.cwd())}`);
   console.log();
 
   const results = { created: 0, skipped: 0, overwritten: 0, failed: 0 };
+  const logs = [];
   const spin = spinner('Downloading files from GitHub...');
 
   try {
@@ -28,41 +38,61 @@ export async function skillsInit({ force = false } = {}) {
         const content = await downloadFile(repoPath);
         const status = safeWrite(destPath, content, { force });
         results[status]++;
-
-        const icon = status === 'created' ? '\u2713'
-          : status === 'overwritten' ? '\u21BB'
-          : '\u2022';
-        const label = status === 'skipped' ? dim(`${repoPath} (exists, skipped)`)
-          : status === 'overwritten' ? `${repoPath} (updated)`
-          : repoPath;
-
-        // Buffer output — will show after spinner stops
-        results[`_log_${repoPath}`] = `  ${icon} ${label}`;
+        logs.push(fileStatus(repoPath, status, 'use --force to overwrite'));
       } catch (err) {
         results.failed++;
-        results[`_log_${repoPath}`] = `  \u2717 ${repoPath} — ${err.message}`;
+        logs.push(fileStatus(repoPath, 'failed', err.message));
       }
     }
   } finally {
     spin.stop();
   }
 
-  // Print file results
-  for (const repoPath of MANIFEST) {
-    console.log(results[`_log_${repoPath}`]);
-  }
+  // Group output by section
+  console.log(`  ${bold('IDE Agent Skills')}`);
+  for (let i = 0; i < SKILLS_FILES.length; i++) logs[i] && console.log(logs[i]);
   console.log();
-
-  // Summary
-  if (results.created > 0) success(`${results.created} file(s) created`);
-  if (results.overwritten > 0) success(`${results.overwritten} file(s) updated`);
-  if (results.skipped > 0) warn(`${results.skipped} file(s) skipped (already exist — use ${bold('--force')} to overwrite)`);
-  if (results.failed > 0) error(`${results.failed} file(s) failed to download`);
-
-  // Next steps
+  console.log(`  ${bold('Persistent Agent (OpenClaw)')}`);
+  for (let i = SKILLS_FILES.length; i < SKILLS_FILES.length + OPENCLAW_FILES.length; i++) logs[i] && console.log(logs[i]);
   console.log();
-  info(bold('Next steps:'));
-  console.log(`  1. Open your IDE agent and say: ${bold('"generate skills for my project"')}`);
-  console.log(`  2. Start the persistent agent: ${bold('serpentstack skills persistent --start')}`);
+  console.log(`  ${bold('Documentation')}`);
+  for (let i = SKILLS_FILES.length + OPENCLAW_FILES.length; i < logs.length; i++) logs[i] && console.log(logs[i]);
+  console.log();
+
+  // Summary line
+  const parts = [];
+  if (results.created > 0) parts.push(green(`${results.created} created`));
+  if (results.overwritten > 0) parts.push(`${results.overwritten} updated`);
+  if (results.skipped > 0) parts.push(`${results.skipped} skipped`);
+  if (results.failed > 0) parts.push(`${results.failed} failed`);
+  console.log(`  ${parts.join(dim(' \u2022 '))}`);
   console.log();
+
+  // Next steps with copyable prompt
+  if (results.failed === MANIFEST.length) {
+    error('All downloads failed. Check your internet connection and try again.');
+    return;
+  }
+
+  printBox('Next steps', [
+    `${bold('1.')} Open your IDE agent (Claude Code, Cursor, Copilot, etc.)`,
+    `   and give it the prompt below to generate project-specific skills.`,
+    '',
+    `${bold('2.')} Start the persistent background agent:`,
+    `   ${dim('$')} ${bold('serpentstack skills persistent --start')}`,
+    '',
+    `${bold('3.')} Customize your persistent agent identity:`,
+    `   ${dim('$')} ${bold('serpentstack skills persistent --create')}`,
+  ]);
+
+  printPrompt([
+    `Read .skills/generate-skills/SKILL.md and follow its instructions`,
+    `to generate project-specific skills for this codebase. Interview me`,
+    `about my architecture decisions — how I handle transactions, auth,`,
+    `error patterns, testing strategy, and deployment. Ask about the`,
+    `business domain too: what this app does, key user flows, and where`,
+    `agents are most likely to make mistakes. Write each skill as a`,
+    `SKILL.md with complete templates an agent can copy, not vague`,
+    `descriptions. Reference SKILL-AUTHORING.md for the format.`,
+  ]);
 }

package/lib/commands/skills-update.js

@@ -2,7 +2,7 @@ import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { downloadFile } from '../utils/github.js';
 import { safeWrite } from '../utils/fs-helpers.js';
-import { info, success, warn, error, spinner, bold, dim } from '../utils/ui.js';
+import { info, success, warn, error, spinner, bold, dim, green, fileStatus } from '../utils/ui.js';
 
 const MANIFEST = [
   '.skills/find-skills/SKILL.md',
@@ -19,6 +19,7 @@ const MANIFEST = [
 const CUSTOMIZABLE = new Set(['.openclaw/SOUL.md', '.openclaw/HEARTBEAT.md', '.openclaw/AGENTS.md']);
 
 export async function skillsUpdate({ force = false, all = false } = {}) {
+  console.log();
   info(`Updating SerpentStack skills in ${bold(process.cwd())}`);
   console.log();
 
@@ -32,7 +33,7 @@ export async function skillsUpdate({ force = false, all = false } = {}) {
 
       // By default, only update files that already exist locally
       if (!existsSync(destPath) && !all) {
-        logs.push(`  \u2022 ${dim(`${repoPath} (not installed — use ${bold('--all')} to add)`)}`);
+        logs.push(fileStatus(repoPath, 'skipped', `not installed \u2014 use ${bold('--all')} to add`));
         results.skipped++;
         continue;
       }
@@ -44,25 +45,25 @@ export async function skillsUpdate({ force = false, all = false } = {}) {
         if (existsSync(destPath)) {
           const local = readFileSync(destPath, 'utf8');
           if (local === content) {
-            logs.push(`  \u2022 ${dim(`${repoPath} (up to date)`)}`);
+            logs.push(fileStatus(repoPath, 'unchanged'));
             results.unchanged++;
             continue;
           }
 
           // Warn about customizable files
           if (CUSTOMIZABLE.has(repoPath) && !force) {
-            logs.push(`  ! ${repoPath} (has local changes — use ${bold('--force')} to overwrite)`);
+            logs.push(fileStatus(repoPath, 'skipped', `local changes \u2014 use ${bold('--force')} to overwrite`));
             results.skipped++;
             continue;
           }
         }
 
         const status = safeWrite(destPath, content, { force: true });
-        logs.push(`  \u21BB ${repoPath} (${status})`);
+        logs.push(fileStatus(repoPath, status === 'created' ? 'created' : 'overwritten'));
         results.updated++;
       } catch (err) {
         results.failed++;
-        logs.push(`  \u2717 ${repoPath} — ${err.message}`);
+        logs.push(fileStatus(repoPath, 'failed', err.message));
       }
     }
   } finally {
@@ -72,9 +73,12 @@ export async function skillsUpdate({ force = false, all = false } = {}) {
   for (const log of logs) console.log(log);
   console.log();
 
-  if (results.updated > 0) success(`${results.updated} file(s) updated`);
-  if (results.unchanged > 0) info(`${results.unchanged} file(s) already up to date`);
-  if (results.skipped > 0) warn(`${results.skipped} file(s) skipped`);
-  if (results.failed > 0) error(`${results.failed} file(s) failed`);
+  // Summary line
+  const parts = [];
+  if (results.updated > 0) parts.push(green(`${results.updated} updated`));
+  if (results.unchanged > 0) parts.push(`${results.unchanged} up to date`);
+  if (results.skipped > 0) parts.push(`${results.skipped} skipped`);
+  if (results.failed > 0) parts.push(`${results.failed} failed`);
+  console.log(`  ${parts.join(dim(' \u2022 '))}`);
   console.log();
 }

package/lib/commands/stack-new.js

@@ -3,7 +3,7 @@ import { rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { execFile } from 'node:child_process';
 import { cloneRepo, checkGit } from '../utils/github.js';
-import { info, success, error, spinner, bold } from '../utils/ui.js';
+import { info, success, error, spinner, bold, dim, green, printBox, printPrompt } from '../utils/ui.js';
 
 const CLEANUP_PATHS = [
   'cli',
@@ -41,11 +41,13 @@ export async function stackNew(name) {
     process.exit(1);
   }
 
+  console.log();
+
   // Clone
   const spin = spinner(`Cloning SerpentStack template into ${name}/...`);
   try {
     await cloneRepo(dest);
-    spin.stop(success(`Template cloned into ${bold(name)}/`));
+    spin.stop(success(`Template cloned into ${green(name)}/`));
   } catch (err) {
     spin.stop();
     error(err.message);
@@ -69,12 +71,31 @@ export async function stackNew(name) {
   });
   success('Initialized fresh git repository');
 
-  // Next steps
+  // What was created
   console.log();
-  info(bold('Next steps:'));
-  console.log(`  cd ${name}`);
-  console.log(`  make init      ${bold('#')} interactive project setup`);
-  console.log(`  make setup     ${bold('#')} install dependencies`);
-  console.log(`  make dev       ${bold('#')} start dev server`);
+  console.log(`  ${dim('Includes:')}`);
+  console.log(`  ${green('\u2713')} FastAPI backend with async SQLAlchemy + JWT auth`);
+  console.log(`  ${green('\u2713')} React frontend with TypeScript + shadcn/ui`);
+  console.log(`  ${green('\u2713')} PostgreSQL + Redis via Docker Compose`);
+  console.log(`  ${green('\u2713')} Terraform infrastructure (AWS App Runner)`);
+  console.log(`  ${green('\u2713')} 10 project-specific Agent Skills in .skills/`);
+  console.log(`  ${green('\u2713')} OpenClaw persistent agent configs in .openclaw/`);
   console.log();
+
+  printBox('Get started', [
+    `${dim('$')} ${bold(`cd ${name}`)}`,
+    `${dim('$')} ${bold('make init')}      ${dim('# interactive project setup')}`,
+    `${dim('$')} ${bold('make setup')}     ${dim('# install dependencies')}`,
+    `${dim('$')} ${bold('make dev')}       ${dim('# start dev server')}`,
+    '',
+    `Then open your IDE agent and start building.`,
+    `The agent reads ${bold('.skills/')} automatically.`,
+  ]);
+
+  printPrompt([
+    `Read .skills/scaffold/SKILL.md and add a Projects resource with`,
+    `full CRUD, JWT auth, and ownership enforcement. Follow the`,
+    `service/route/test/frontend patterns exactly as the skill`,
+    `describes. Run make verify when done to confirm everything passes.`,
+  ], { hint: 'Try this prompt to verify your skills are working' });
 }

package/lib/commands/stack-update.js

@@ -2,7 +2,7 @@ import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { downloadFile } from '../utils/github.js';
 import { safeWrite } from '../utils/fs-helpers.js';
-import { info, success, warn, error, spinner, bold, dim } from '../utils/ui.js';
+import { info, success, warn, error, spinner, bold, dim, green, fileStatus } from '../utils/ui.js';
 
 // Template-level files that may be updated upstream
 const TEMPLATE_FILES = [
@@ -20,6 +20,7 @@ export async function stackUpdate({ force = false } = {}) {
     process.exit(1);
   }
 
+  console.log();
   info(`Checking for template updates in ${bold(process.cwd())}`);
   console.log();
 
@@ -36,18 +37,18 @@ export async function stackUpdate({ force = false } = {}) {
         if (existsSync(destPath)) {
           const local = readFileSync(destPath, 'utf8');
           if (local === content) {
-            logs.push(`  \u2022 ${dim(`${repoPath} (up to date)`)}`);
+            logs.push(fileStatus(repoPath, 'unchanged'));
             results.unchanged++;
             continue;
           }
         }
 
         const status = safeWrite(destPath, content, { force: true });
-        logs.push(`  \u21BB ${repoPath} (${status})`);
+        logs.push(fileStatus(repoPath, status === 'created' ? 'created' : 'overwritten'));
         results.updated++;
       } catch (err) {
         results.failed++;
-        logs.push(`  \u2717 ${repoPath} — ${err.message}`);
+        logs.push(fileStatus(repoPath, 'failed', err.message));
       }
     }
   } finally {
@@ -57,8 +58,11 @@ export async function stackUpdate({ force = false } = {}) {
   for (const log of logs) console.log(log);
   console.log();
 
-  if (results.updated > 0) success(`${results.updated} file(s) updated`);
-  if (results.unchanged > 0) info(`${results.unchanged} file(s) already up to date`);
-  if (results.failed > 0) error(`${results.failed} file(s) failed`);
+  // Summary line
+  const parts = [];
+  if (results.updated > 0) parts.push(green(`${results.updated} updated`));
+  if (results.unchanged > 0) parts.push(`${results.unchanged} up to date`);
+  if (results.failed > 0) parts.push(`${results.failed} failed`);
+  console.log(`  ${parts.join(dim(' \u2022 '))}`);
   console.log();
 }

package/lib/utils/ui.js

@@ -8,17 +8,27 @@ const c = (code) => NO_COLOR ? '' : `\x1b[${code}m`;
 const RESET = c(0);
 const BOLD = c(1);
 const DIM = c(2);
+const ITALIC = c(3);
 const RED = c(31);
 const GREEN = c(32);
 const YELLOW = c(33);
+const BLUE = c(34);
+const MAGENTA = c(35);
 const CYAN = c(36);
+const BG_DIM = c(100);
 
-export const info = (msg) => console.log(`${CYAN}i${RESET} ${msg}`);
+export const info = (msg) => console.log(`${CYAN}\u2022${RESET} ${msg}`);
 export const success = (msg) => console.log(`${GREEN}\u2713${RESET} ${msg}`);
-export const warn = (msg) => console.log(`${YELLOW}!${RESET} ${msg}`);
+export const warn = (msg) => console.log(`${YELLOW}\u25B3${RESET} ${msg}`);
 export const error = (msg) => console.error(`${RED}\u2717${RESET} ${msg}`);
 export const dim = (msg) => `${DIM}${msg}${RESET}`;
 export const bold = (msg) => `${BOLD}${msg}${RESET}`;
+export const green = (msg) => `${GREEN}${msg}${RESET}`;
+export const yellow = (msg) => `${YELLOW}${msg}${RESET}`;
+export const red = (msg) => `${RED}${msg}${RESET}`;
+export const cyan = (msg) => `${CYAN}${msg}${RESET}`;
+export const magenta = (msg) => `${MAGENTA}${msg}${RESET}`;
+export const blue = (msg) => `${BLUE}${msg}${RESET}`;
 
 const SPINNER_FRAMES = ['\u280B', '\u2819', '\u2839', '\u2838', '\u283C', '\u2834', '\u2826', '\u2827', '\u2807', '\u280F'];
 
@@ -60,5 +70,82 @@ export function getVersion() {
 }
 
 export function printHeader() {
-  console.log(`\n  ${BOLD}${CYAN}\u2728 SerpentStack${RESET} ${DIM}v${getVersion()}${RESET}\n`);
+  console.log(`\n  ${BOLD}${GREEN}\u2728 SerpentStack${RESET} ${DIM}v${getVersion()}${RESET}\n`);
+}
+
+/**
+ * Print a boxed section with a title and content lines.
+ * Used for "Next steps" and prompt blocks.
+ */
+export function printBox(title, lines, { color = GREEN, icon = '\u25B6' } = {}) {
+  const maxLen = Math.max(
+    title.length + 4,
+    ...lines.map(l => stripAnsi(l).length + 4)
+  );
+  const width = Math.min(Math.max(maxLen, 50), 80);
+  const top = `${color}\u250C${'─'.repeat(width)}\u2510${RESET}`;
+  const bot = `${color}\u2514${'─'.repeat(width)}\u2518${RESET}`;
+
+  console.log(top);
+  console.log(`${color}\u2502${RESET} ${BOLD}${icon} ${title}${RESET}${' '.repeat(Math.max(0, width - stripAnsi(title).length - 3))}${color}\u2502${RESET}`);
+  console.log(`${color}\u2502${' '.repeat(width)}${color}\u2502${RESET}`);
+  for (const line of lines) {
+    const pad = Math.max(0, width - stripAnsi(line).length - 2);
+    console.log(`${color}\u2502${RESET}  ${line}${' '.repeat(pad)}${color}\u2502${RESET}`);
+  }
+  console.log(bot);
+}
+
+/**
+ * Print a copyable prompt block that the user can paste into their IDE agent.
+ * Accepts a single string or an array of lines for multi-line prompts.
+ */
+export function printPrompt(promptLines, { hint = 'Copy this prompt and paste it into your IDE agent' } = {}) {
+  const lines = Array.isArray(promptLines) ? promptLines : [promptLines];
+  const maxLineLen = Math.max(...lines.map(l => stripAnsi(l).length));
+  const width = Math.min(Math.max(maxLineLen + 6, 50), 90);
+  const innerWidth = width - 2;
+
+  console.log();
+  console.log(`  ${DIM}\u250C${'─'.repeat(innerWidth)}\u2510${RESET}`);
+  for (const line of lines) {
+    const pad = Math.max(0, innerWidth - stripAnsi(line).length - 2);
+    console.log(`  ${DIM}\u2502${RESET} ${CYAN}${line}${RESET}${' '.repeat(pad)}${DIM}\u2502${RESET}`);
+  }
+  console.log(`  ${DIM}\u2514${'─'.repeat(innerWidth)}\u2518${RESET}`);
+  console.log(`  ${DIM}\u2191 ${hint}${RESET}`);
+  console.log();
+}
+
+/**
+ * File status icon with color.
+ */
+export function fileIcon(status) {
+  switch (status) {
+    case 'created': return `${GREEN}\u2713${RESET}`;
+    case 'overwritten': return `${CYAN}\u21BB${RESET}`;
+    case 'skipped': return `${YELLOW}\u2022${RESET}`;
+    case 'failed': return `${RED}\u2717${RESET}`;
+    case 'unchanged': return `${DIM}\u2022${RESET}`;
+    default: return `${DIM}\u2022${RESET}`;
+  }
+}
+
+/**
+ * Format a file path with its status for display.
+ */
+export function fileStatus(path, status, detail) {
+  const icon = fileIcon(status);
+  switch (status) {
+    case 'created': return `  ${icon} ${green(path)}`;
+    case 'overwritten': return `  ${icon} ${cyan(path)} ${dim('(updated)')}`;
+    case 'skipped': return `  ${icon} ${dim(`${path} (${detail || 'exists, skipped'})`)}`;
+    case 'failed': return `  ${icon} ${red(path)} ${dim(`\u2014 ${detail}`)}`;
+    case 'unchanged': return `  ${icon} ${dim(`${path} (up to date)`)}`;
+    default: return `  ${icon} ${path}`;
+  }
+}
+
+function stripAnsi(str) {
+  return str.replace(/\x1b\[\d+m/g, '');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serpentstack",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI for SerpentStack — AI-driven development standards with project-specific skills and persistent agents",
   "type": "module",
   "bin": {