serpentstack 0.1.0

package/bin/serpentstack.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+import { error, bold, getVersion, printHeader } from '../lib/utils/ui.js';
+
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+  for (const arg of args) {
+    if (arg.startsWith('--')) {
+      const [key, val] = arg.slice(2).split('=');
+      flags[key] = val ?? true;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+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('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('Options:')}
+    --force                       Overwrite existing files
+    --all                         Include new files in updates (skills update)
+    --version                     Show version
+    --help                        Show this help
+`);
+}
+
+async function main() {
+  const [,, noun, verb, ...rest] = process.argv;
+  const { flags, positional } = parseFlags(rest);
+
+  // Top-level flags
+  if (noun === '--version' || flags.version) {
+    console.log(getVersion());
+    return;
+  }
+  if (!noun || noun === '--help' || flags.help) {
+    showHelp();
+    return;
+  }
+
+  if (noun === 'stack') {
+    if (verb === 'new') {
+      const { stackNew } = await import('../lib/commands/stack-new.js');
+      await stackNew(positional[0]);
+    } else if (verb === 'update') {
+      const { stackUpdate } = await import('../lib/commands/stack-update.js');
+      await stackUpdate({ force: !!flags.force });
+    } else {
+      error(`Unknown stack command: ${verb}`);
+      console.log(`\n  Available: ${bold('stack new <name>')}, ${bold('stack update')}\n`);
+      process.exit(1);
+    }
+  } else if (noun === 'skills') {
+    if (verb === 'init') {
+      const { skillsInit } = await import('../lib/commands/skills-init.js');
+      await skillsInit({ force: !!flags.force });
+    } else if (verb === 'update') {
+      const { skillsUpdate } = await import('../lib/commands/skills-update.js');
+      await skillsUpdate({ force: !!flags.force, all: !!flags.all });
+    } else if (verb === 'persistent') {
+      const { skillsPersistent } = await import('../lib/commands/skills-persistent.js');
+      await skillsPersistent({
+        create: !!flags.create,
+        start: !!flags.start,
+        stop: !!flags.stop,
+      });
+    } else {
+      error(`Unknown skills command: ${verb}`);
+      console.log(`\n  Available: ${bold('skills init')}, ${bold('skills update')}, ${bold('skills persistent')}\n`);
+      process.exit(1);
+    }
+  } else {
+    error(`Unknown command: ${noun}`);
+    showHelp();
+    process.exit(1);
+  }
+}
+
+// Global error handling
+process.on('unhandledRejection', (err) => {
+  error(err.message || 'An unexpected error occurred');
+  if (process.env.DEBUG) console.error(err.stack);
+  process.exit(1);
+});
+
+main().catch((err) => {
+  error(err.message || 'An unexpected error occurred');
+  if (process.env.DEBUG) console.error(err.stack);
+  process.exit(1);
+});

package/lib/commands/skills-init.js

@@ -0,0 +1,68 @@
+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';
+
+const MANIFEST = [
+  '.skills/find-skills/SKILL.md',
+  '.skills/generate-skills/SKILL.md',
+  '.skills/git-workflow/SKILL.md',
+  '.skills/model-routing/SKILL.md',
+  '.openclaw/SOUL.md',
+  '.openclaw/HEARTBEAT.md',
+  '.openclaw/AGENTS.md',
+  'SKILL-AUTHORING.md',
+];
+
+export async function skillsInit({ force = false } = {}) {
+  info(`Downloading SerpentStack skills into ${bold(process.cwd())}`);
+  console.log();
+
+  const results = { created: 0, skipped: 0, overwritten: 0, failed: 0 };
+  const spin = spinner('Downloading files from GitHub...');
+
+  try {
+    for (const repoPath of MANIFEST) {
+      const destPath = join(process.cwd(), repoPath);
+      try {
+        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}`;
+      } catch (err) {
+        results.failed++;
+        results[`_log_${repoPath}`] = `  \u2717 ${repoPath} — ${err.message}`;
+      }
+    }
+  } finally {
+    spin.stop();
+  }
+
+  // Print file results
+  for (const repoPath of MANIFEST) {
+    console.log(results[`_log_${repoPath}`]);
+  }
+  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();
+  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();
+}

package/lib/commands/skills-persistent.js

@@ -0,0 +1,148 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFile, spawn } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { info, success, warn, error, confirm, bold, dim } from '../utils/ui.js';
+
+function which(cmd) {
+  return new Promise((resolve) => {
+    execFile('which', [cmd], (err) => resolve(!err));
+  });
+}
+
+function checkOpenClawWorkspace() {
+  const dir = join(process.cwd(), '.openclaw');
+  const required = ['SOUL.md', 'HEARTBEAT.md', 'AGENTS.md'];
+  if (!existsSync(dir)) return false;
+  return required.every((f) => existsSync(join(dir, f)));
+}
+
+async function persistentCreate() {
+  if (!checkOpenClawWorkspace()) {
+    error('No .openclaw/ workspace found. Run `serpentstack skills init` first.');
+    process.exit(1);
+  }
+
+  info('Customizing OpenClaw workspace for your project...');
+  console.log();
+
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const name = await rl.question(`  Project name: `);
+    const lang = await rl.question(`  Primary language ${dim('(e.g., Python, TypeScript)')}: `);
+    const framework = await rl.question(`  Framework ${dim('(e.g., FastAPI, Next.js, Django)')}: `);
+    const conventions = await rl.question(`  Key conventions ${dim('(brief, e.g., "services flush, routes commit")')}: `);
+
+    console.log();
+
+    // Read and update SOUL.md with project-specific info
+    const { readFileSync, writeFileSync } = await import('node:fs');
+    const soulPath = join(process.cwd(), '.openclaw/SOUL.md');
+    let soul = readFileSync(soulPath, 'utf8');
+
+    // Prepend project-specific context
+    const projectContext = [
+      `# ${name} — Persistent Development Agent`,
+      '',
+      `**Project:** ${name}`,
+      `**Language:** ${lang}`,
+      `**Framework:** ${framework}`,
+      `**Conventions:** ${conventions}`,
+      '',
+      '---',
+      '',
+    ].join('\n');
+
+    // Replace the first heading and everything before the first ---
+    const dashIndex = soul.indexOf('---');
+    if (dashIndex !== -1) {
+      soul = projectContext + soul.slice(dashIndex + 3).trimStart();
+    } else {
+      soul = projectContext + soul;
+    }
+
+    writeFileSync(soulPath, soul, 'utf8');
+    success(`Updated .openclaw/SOUL.md with ${bold(name)} project context`);
+    info(`Review and customize .openclaw/ files, then run: ${bold('serpentstack skills persistent --start')}`);
+  } finally {
+    rl.close();
+  }
+  console.log();
+}
+
+async function persistentStart() {
+  if (!checkOpenClawWorkspace()) {
+    error('No .openclaw/ workspace found. Run `serpentstack skills init` first.');
+    process.exit(1);
+  }
+
+  const hasOpenClaw = await which('openclaw');
+  if (!hasOpenClaw) {
+    warn('OpenClaw is not installed.');
+    const install = await confirm('Install OpenClaw now? (npm install -g openclaw@latest)');
+    if (!install) {
+      info(`Install manually: ${bold('npm install -g openclaw@latest')}`);
+      return;
+    }
+    info('Installing OpenClaw...');
+    await new Promise((resolve, reject) => {
+      const child = spawn('npm', ['install', '-g', 'openclaw@latest'], { stdio: 'inherit' });
+      child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`npm install exited with code ${code}`)));
+    });
+    success('OpenClaw installed');
+    console.log();
+  }
+
+  info('Starting persistent agent...');
+  const child = spawn('openclaw', ['start', '--workspace', '.openclaw/'], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+  });
+
+  child.on('error', (err) => {
+    error(`Failed to start OpenClaw: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on('close', (code) => {
+    if (code !== 0) {
+      error(`OpenClaw exited with code ${code}`);
+      process.exit(code);
+    }
+  });
+}
+
+async function persistentStop() {
+  const hasOpenClaw = await which('openclaw');
+  if (!hasOpenClaw) {
+    error('OpenClaw is not installed. Nothing to stop.');
+    return;
+  }
+
+  info('Stopping persistent agent...');
+  await new Promise((resolve, reject) => {
+    execFile('openclaw', ['stop'], (err, _stdout, stderr) => {
+      if (err) {
+        reject(new Error(stderr || err.message));
+      } else {
+        resolve();
+      }
+    });
+  });
+  success('Persistent agent stopped');
+}
+
+export async function skillsPersistent({ create = false, start = false, stop = false } = {}) {
+  if (create) return persistentCreate();
+  if (start) return persistentStart();
+  if (stop) return persistentStop();
+
+  error('Specify an action: --create, --start, or --stop');
+  console.log();
+  console.log(`  ${bold('serpentstack skills persistent --create')}  Set up the workspace`);
+  console.log(`  ${bold('serpentstack skills persistent --start')}   Start the background agent`);
+  console.log(`  ${bold('serpentstack skills persistent --stop')}    Stop the background agent`);
+  console.log();
+  process.exit(1);
+}

package/lib/commands/skills-update.js

@@ -0,0 +1,80 @@
+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';
+
+const MANIFEST = [
+  '.skills/find-skills/SKILL.md',
+  '.skills/generate-skills/SKILL.md',
+  '.skills/git-workflow/SKILL.md',
+  '.skills/model-routing/SKILL.md',
+  '.openclaw/SOUL.md',
+  '.openclaw/HEARTBEAT.md',
+  '.openclaw/AGENTS.md',
+  'SKILL-AUTHORING.md',
+];
+
+// OpenClaw files are meant to be customized — warn before overwriting
+const CUSTOMIZABLE = new Set(['.openclaw/SOUL.md', '.openclaw/HEARTBEAT.md', '.openclaw/AGENTS.md']);
+
+export async function skillsUpdate({ force = false, all = false } = {}) {
+  info(`Updating SerpentStack skills in ${bold(process.cwd())}`);
+  console.log();
+
+  const results = { updated: 0, skipped: 0, unchanged: 0, failed: 0 };
+  const spin = spinner('Checking for updates...');
+  const logs = [];
+
+  try {
+    for (const repoPath of MANIFEST) {
+      const destPath = join(process.cwd(), repoPath);
+
+      // 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)`)}`);
+        results.skipped++;
+        continue;
+      }
+
+      try {
+        const content = await downloadFile(repoPath);
+
+        // Check if local content is identical
+        if (existsSync(destPath)) {
+          const local = readFileSync(destPath, 'utf8');
+          if (local === content) {
+            logs.push(`  \u2022 ${dim(`${repoPath} (up to date)`)}`);
+            results.unchanged++;
+            continue;
+          }
+
+          // Warn about customizable files
+          if (CUSTOMIZABLE.has(repoPath) && !force) {
+            logs.push(`  ! ${repoPath} (has local changes — use ${bold('--force')} to overwrite)`);
+            results.skipped++;
+            continue;
+          }
+        }
+
+        const status = safeWrite(destPath, content, { force: true });
+        logs.push(`  \u21BB ${repoPath} (${status})`);
+        results.updated++;
+      } catch (err) {
+        results.failed++;
+        logs.push(`  \u2717 ${repoPath} — ${err.message}`);
+      }
+    }
+  } finally {
+    spin.stop();
+  }
+
+  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`);
+  console.log();
+}

package/lib/commands/stack-new.js

@@ -0,0 +1,80 @@
+import { existsSync } from 'node:fs';
+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';
+
+const CLEANUP_PATHS = [
+  'cli',
+  'references',
+  'BRIEF.md',
+  'PRINCIPLES.md',
+];
+
+function validateName(name) {
+  if (!name) return 'Project name is required';
+  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name)) {
+    return 'Name must start with a letter and contain only letters, numbers, hyphens, and underscores';
+  }
+  return null;
+}
+
+export async function stackNew(name) {
+  const nameError = validateName(name);
+  if (nameError) {
+    error(nameError);
+    console.log(`\n  Usage: ${bold('serpentstack stack new <project-name>')}\n`);
+    process.exit(1);
+  }
+
+  const dest = resolve(process.cwd(), name);
+
+  if (existsSync(dest)) {
+    error(`Directory ${bold(name)} already exists`);
+    process.exit(1);
+  }
+
+  const hasGit = await checkGit();
+  if (!hasGit) {
+    error('git is not installed. Install git first: https://git-scm.com/downloads');
+    process.exit(1);
+  }
+
+  // Clone
+  const spin = spinner(`Cloning SerpentStack template into ${name}/...`);
+  try {
+    await cloneRepo(dest);
+    spin.stop(success(`Template cloned into ${bold(name)}/`));
+  } catch (err) {
+    spin.stop();
+    error(err.message);
+    process.exit(1);
+  }
+
+  // Clean up repo-specific files
+  for (const p of CLEANUP_PATHS) {
+    const full = join(dest, p);
+    if (existsSync(full)) {
+      await rm(full, { recursive: true, force: true });
+    }
+  }
+
+  // Initialize fresh git repo
+  await new Promise((resolve, reject) => {
+    execFile('git', ['init'], { cwd: dest }, (err) => {
+      if (err) reject(new Error(`git init failed: ${err.message}`));
+      else resolve();
+    });
+  });
+  success('Initialized fresh git repository');
+
+  // Next steps
+  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();
+}

package/lib/commands/stack-update.js

@@ -0,0 +1,64 @@
+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';
+
+// Template-level files that may be updated upstream
+const TEMPLATE_FILES = [
+  'Makefile',
+  'docker-compose.yml',
+  'scripts/init.py',
+  '.cursorrules',
+  '.github/copilot-instructions.md',
+];
+
+export async function stackUpdate({ force = false } = {}) {
+  // Verify we're in a SerpentStack project
+  if (!existsSync(join(process.cwd(), 'Makefile')) || !existsSync(join(process.cwd(), 'backend'))) {
+    error('Not a SerpentStack project. Run this from a directory created with `serpentstack stack new`.');
+    process.exit(1);
+  }
+
+  info(`Checking for template updates in ${bold(process.cwd())}`);
+  console.log();
+
+  const results = { updated: 0, unchanged: 0, failed: 0 };
+  const spin = spinner('Fetching latest template files...');
+  const logs = [];
+
+  try {
+    for (const repoPath of TEMPLATE_FILES) {
+      const destPath = join(process.cwd(), repoPath);
+      try {
+        const content = await downloadFile(repoPath);
+
+        if (existsSync(destPath)) {
+          const local = readFileSync(destPath, 'utf8');
+          if (local === content) {
+            logs.push(`  \u2022 ${dim(`${repoPath} (up to date)`)}`);
+            results.unchanged++;
+            continue;
+          }
+        }
+
+        const status = safeWrite(destPath, content, { force: true });
+        logs.push(`  \u21BB ${repoPath} (${status})`);
+        results.updated++;
+      } catch (err) {
+        results.failed++;
+        logs.push(`  \u2717 ${repoPath} — ${err.message}`);
+      }
+    }
+  } finally {
+    spin.stop();
+  }
+
+  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`);
+  console.log();
+}

package/lib/utils/fs-helpers.js

@@ -0,0 +1,31 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Write content to a file with overwrite protection.
+ *
+ * @param {string} destPath - Absolute or relative path to write to
+ * @param {string} content  - File content
+ * @param {{ force?: boolean }} options
+ * @returns {'created' | 'overwritten' | 'skipped'}
+ */
+export function safeWrite(destPath, content, { force = false } = {}) {
+  mkdirSync(dirname(destPath), { recursive: true });
+
+  if (existsSync(destPath)) {
+    if (!force) {
+      return 'skipped';
+    }
+    // Don't overwrite if content is identical
+    try {
+      const existing = readFileSync(destPath, 'utf8');
+      if (existing === content) return 'skipped';
+    } catch { /* proceed with overwrite */ }
+
+    writeFileSync(destPath, content, 'utf8');
+    return 'overwritten';
+  }
+
+  writeFileSync(destPath, content, 'utf8');
+  return 'created';
+}

package/lib/utils/github.js

@@ -0,0 +1,74 @@
+import { execFile } from 'node:child_process';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const GITHUB_REPO = process.env.SERPENTSTACK_REPO || 'Benja-Pauls/SerpentStack';
+const GITHUB_BRANCH = process.env.SERPENTSTACK_BRANCH || 'main';
+const RAW_BASE = `https://raw.githubusercontent.com/${GITHUB_REPO}/${GITHUB_BRANCH}`;
+const CLONE_URL = `https://github.com/${GITHUB_REPO}.git`;
+
+function authHeaders() {
+  const token = process.env.GITHUB_TOKEN;
+  return token ? { Authorization: `token ${token}` } : {};
+}
+
+/**
+ * Download a single file from the SerpentStack repo.
+ * Returns the file content as a string.
+ * Retries once on network failure.
+ */
+export async function downloadFile(repoPath) {
+  const url = `${RAW_BASE}/${repoPath}`;
+  let lastError;
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const res = await fetch(url, { headers: authHeaders() });
+      if (res.status === 404) {
+        throw new Error(`File not found: ${repoPath} (checked ${url})`);
+      }
+      if (!res.ok) {
+        throw new Error(`GitHub returned ${res.status} for ${repoPath}`);
+      }
+      return await res.text();
+    } catch (err) {
+      lastError = err;
+      if (attempt === 0 && err.cause?.code === 'ENOTFOUND') {
+        await new Promise((r) => setTimeout(r, 2000));
+      } else {
+        throw err;
+      }
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * Clone the SerpentStack repo into `dest` with --depth=1.
+ * Removes .git/ after cloning so the user starts fresh.
+ */
+export async function cloneRepo(dest) {
+  await new Promise((resolve, reject) => {
+    execFile('git', ['clone', '--depth=1', CLONE_URL, dest], (err, _stdout, stderr) => {
+      if (err) {
+        const msg = stderr?.includes('not found')
+          ? `Could not clone ${CLONE_URL}. Check your internet connection.`
+          : `git clone failed: ${stderr || err.message}`;
+        reject(new Error(msg));
+      } else {
+        resolve();
+      }
+    });
+  });
+
+  await rm(join(dest, '.git'), { recursive: true, force: true });
+}
+
+/**
+ * Check if git is installed.
+ */
+export function checkGit() {
+  return new Promise((resolve) => {
+    execFile('git', ['--version'], (err) => resolve(!err));
+  });
+}

package/lib/utils/ui.js

@@ -0,0 +1,64 @@
+import { createInterface } from 'node:readline/promises';
+import { readFileSync } from 'node:fs';
+import { stdin, stdout, stderr } from 'node:process';
+
+const NO_COLOR = !!process.env.NO_COLOR || !stdout.isTTY;
+
+const c = (code) => NO_COLOR ? '' : `\x1b[${code}m`;
+const RESET = c(0);
+const BOLD = c(1);
+const DIM = c(2);
+const RED = c(31);
+const GREEN = c(32);
+const YELLOW = c(33);
+const CYAN = c(36);
+
+export const info = (msg) => console.log(`${CYAN}i${RESET} ${msg}`);
+export const success = (msg) => console.log(`${GREEN}\u2713${RESET} ${msg}`);
+export const warn = (msg) => console.log(`${YELLOW}!${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}`;
+
+const SPINNER_FRAMES = ['\u280B', '\u2819', '\u2839', '\u2838', '\u283C', '\u2834', '\u2826', '\u2827', '\u2807', '\u280F'];
+
+export function spinner(msg) {
+  if (NO_COLOR || !stderr.isTTY) {
+    stderr.write(`  ${msg}\n`);
+    return { stop(final) { if (final) stderr.write(`  ${final}\n`); } };
+  }
+  let i = 0;
+  const id = setInterval(() => {
+    stderr.write(`\r${CYAN}${SPINNER_FRAMES[i++ % SPINNER_FRAMES.length]}${RESET} ${msg}`);
+  }, 80);
+  return {
+    stop(final) {
+      clearInterval(id);
+      stderr.write(`\r\x1b[K`);
+      if (final) console.log(final);
+    }
+  };
+}
+
+export async function confirm(msg) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question(`${YELLOW}?${RESET} ${msg} ${dim('(y/N)')} `);
+    return answer.trim().toLowerCase() === 'y';
+  } finally {
+    rl.close();
+  }
+}
+
+export function getVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+    return pkg.version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+export function printHeader() {
+  console.log(`\n  ${BOLD}${CYAN}\u2728 SerpentStack${RESET} ${DIM}v${getVersion()}${RESET}\n`);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "serpentstack",
+  "version": "0.1.0",
+  "description": "CLI for SerpentStack — AI-driven development standards with project-specific skills and persistent agents",
+  "type": "module",
+  "bin": {
+    "serpentstack": "./bin/serpentstack.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "skills",
+    "development",
+    "fullstack",
+    "fastapi",
+    "react",
+    "openclaw",
+    "persistent-agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Benja-Pauls/SerpentStack"
+  },
+  "homepage": "https://github.com/Benja-Pauls/SerpentStack#readme",
+  "author": "Ben Paulson"
+}