spectoflow 0.16.2 → 0.16.4

package/bin/postinstall.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * Printed after `npm install -g spectoflow`: the brand welcome + first steps.
+ * Guarded to a GLOBAL, interactive (TTY) install so it never spams CI, dependency installs, or logs,
+ * and wrapped so a banner can never fail an install. Note: npm may buffer lifecycle-script output —
+ * if it doesn't appear, `spectoflow` (no args) and `spectoflow init` show the same brand.
+ */
+try {
+  if (process.env.npm_config_global === 'true' && process.stdout.isTTY) {
+    const brand = require('../lib/brand');
+    const version = require('../package.json').version;
+    const useColor = !process.env.NO_COLOR;
+    const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+    const c = { white: paint('97'), amber: paint('38;5;179'), dim: paint('2'), bold: paint('1'), g: paint('32') };
+    process.stdout.write(brand.logo(c, version));
+    process.stdout.write(`\n  ${c.bold('Get started')}\n`);
+    process.stdout.write(`    ${c.g('spectoflow init')}      scaffold a project in the current folder\n`);
+    process.stdout.write(`    ${c.g('spectoflow --help')}    all commands\n\n`);
+  }
+} catch { /* never break an install over a welcome banner */ }

package/bin/spectoflow.js

@@ -20,46 +20,14 @@ const cmd = argv[0] || 'help';
 // Tiny ANSI colouriser — no dependency; disabled when not a TTY or NO_COLOR is set.
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
-const c = { g: paint('32'), cy: paint('36'), b: paint('34'), y: paint('33'), dim: paint('2'), bold: paint('1'), amber: paint('38;5;179') };
+const c = { g: paint('32'), cy: paint('36'), b: paint('34'), y: paint('33'), dim: paint('2'), bold: paint('1'), amber: paint('38;5;179'), white: paint('97') };
 
 // ---- branding ---------------------------------------------------------------
-// The spectoflow mark in ASCII: a flat-top hexagon around the angular "S" (flow), rasterized to fit
-// a terminal. Shown at the reading moments (init / help / list); secondary outputs use brandLine().
-const LOGO = [
-  '                  ########',
-  '               ######  #######',
-  '           #######         ######',
-  '         ######               ######',
-  '      ######          ####       ######',
-  '    #####          ######           ####',
-  '    ###         ######               ####',
-  '    ###       #####                  ####',
-  '    ###      ####       ##           ####',
-  '    ###      ####    #########       ####',
-  '    ###      #### ####### #####      ####',
-  '    ###       ########      ###      ####',
-  '    ###          ##         ###      ####',
-  '    ###                    ####      ####',
-  '    ###                 ######       ####',
-  '    ###              ######          ####',
-  '    ####          ######            ####',
-  '     ######       ###            ######',
-  '        ######                ######',
-  '           ######          ######',
-  '              ######    ######',
-  '                 ##########',
-  '                    ####',
-];
-const LOGO_W = 41;                       // widest logo line, for centering the wordmark under it
-const NAME = 's p e c t o f l o w';
-const TAGLINE = 'agent-agnostic spec-driven development · real-time control plane';
-// Full logo block — hexagon mark + centered wordmark + version. For init, help and list.
-function logo() {
-  const art = LOGO.map((l) => '  ' + c.amber(l)).join('\n');
-  const pad = ' '.repeat(Math.max(0, Math.round((2 + LOGO_W - NAME.length) / 2)));
-  return `\n${art}\n\n${pad}${c.bold(c.amber(NAME))}\n  ${c.dim('v' + VERSION + ' · ' + TAGLINE)}\n`;
-}
-// One-line brand — for the header of secondary command outputs.
+// Shared ASCII brand (white hexagon + amber wordmark) lives in lib/brand.js so the CLI and the
+// postinstall welcome render the exact same art.
+const brand = require('../lib/brand');
+const logo = () => brand.logo(c, VERSION);        // white hexagon + centered amber wordmark (init/update)
+const wordmark = () => brand.wordmark(c, VERSION); // amber wordmark alone (help + explore)
 const brandLine = () => `${c.amber('spectoflow')} ${c.dim('v' + VERSION)}`;
 
 // ---- framework introspection (list agents / skills / workflow) --------------
@@ -266,7 +234,7 @@ function update() {
     const detail = note ? c.dim(note) : c.dim(list.slice(0, 6).join(', ') + (list.length > 6 ? ` +${list.length - 6} more` : ''));
     console.log(`  ${sym}  ${painter(label.padEnd(9))} ${n}   ${detail}`);
   };
-  console.log('');
+  console.log(logo());
   console.log(`  ${c.bold('spectoflow update')}   ${c.dim(from)} ${c.amber('→')} ${c.bold(r.toVersion)}${dryRun ? c.dim('   (dry-run)') : ''}`);
   console.log('');
   row(c.g('✓'), 'refreshed', r.refreshed, c.g);
@@ -403,7 +371,7 @@ function printWorkflow(withBrand = true) {
 }
 function listAll() {
   const { scope } = frameworkSource();
-  console.log(logo());
+  console.log(wordmark());
   console.log(`${c.bold('Agents')} ${c.dim('— stable team personas (' + scope + ')')}`);
   printAgents(false);
   console.log(`\n${c.bold('Skills')} ${c.dim('— evolving procedures')}`);
@@ -414,7 +382,7 @@ function listAll() {
 }
 
 // ---- help (global + per-command) --------------------------------------------
-const help = () => console.log(`${logo()}
+const help = () => console.log(`${wordmark()}
 ${c.dim('Usage:')} spectoflow ${c.g('<command>')} ${c.dim('[options]')}   ${c.dim('· append -h to any command for its help')}
 
 ${c.bold('Project')}
@@ -473,7 +441,12 @@ const HELP = {
 const showHelp = (name) => console.log('\n' + HELP[name].trim() + '\n');
 
 // ---- dispatch ---------------------------------------------------------------
-const fns = { init, update, dashboard, stop: stopDashboard, status, list: listAll, agents: () => printAgents(), skills: () => printSkills(), workflow: () => printWorkflow(), help, version };
+const fns = {
+  init, update, dashboard, stop: stopDashboard, status, list: listAll, help, version,
+  agents: () => { console.log(wordmark()); printAgents(false); },
+  skills: () => { console.log(wordmark()); printSkills(false); },
+  workflow: () => { console.log(wordmark()); printWorkflow(false); },
+};
 const wantsHelp = argv.slice(1).some((a) => a === '-h' || a === '--help');
 
 if (['-v', '-V', '--version', 'version'].includes(cmd)) version();

package/lib/brand.js

@@ -0,0 +1,64 @@
+'use strict';
+/*
+ * Shared spectoflow ASCII brand — used by the CLI (bin/spectoflow.js) and the postinstall welcome
+ * (bin/postinstall.js). The hexagon mark is drawn WHITE; the compact figlet wordmark is drawn AMBER
+ * and centred under the mark. Callers pass their own colouriser `c` (with .white/.amber/.dim) and the
+ * version string, so this stays presentation-agnostic and zero-dependency.
+ */
+const LOGO = [
+  '                  ########',
+  '               ######  #######',
+  '           #######         ######',
+  '         ######               ######',
+  '      ######          ####       ######',
+  '    #####          ######           ####',
+  '    ####         ######               ####',
+  '    ####       #####                  ####',
+  '    ####      ####       ##           ####',
+  '    ####      ####    #########       ####',
+  '    ####      #### ####### #####      ####',
+  '    ####       ########      ###      ####',
+  '    ####          ##         ###      ####',
+  '    ####                    ####      ####',
+  '    ####                 ######       ####',
+  '    ####              ######          ####',
+  '    ####          ######            ####',
+  '     ######       ###            ######',
+  '        ######                ######',
+  '           ######          ######',
+  '              ######    ######',
+  '                 ##########',
+  '                    ####',
+];
+const NAME = [
+  '                  _        __ _',
+  '  ____ __  ___ __| |_ ___ / _| |_____ __ __',
+  " (_-< '_ \\/ -_) _|  _/ _ \\  _| / _ \\ V  V /",
+  ' /__/ .__/\\___\\__|\\__\\___/_| |_\\___/\\_/\\_/',
+  '    |_|',
+];
+const NAME_W = Math.max(...NAME.map((l) => l.length));
+const TAGLINE = 'agent-agnostic spec-driven development · real-time control plane';
+const INDENT = '  ';
+
+// Amber wordmark; when `centerUnder`, centred beneath the hexagon's true horizontal midpoint.
+function nameBlock(c, centerUnder) {
+  let pad = INDENT;
+  if (centerUnder) {
+    let lo = Infinity, hi = 0;
+    for (const l of LOGO) { const i = l.search(/#/); if (i >= 0) { lo = Math.min(lo, i); hi = Math.max(hi, l.length - 1); } }
+    pad = ' '.repeat(Math.max(0, Math.round(INDENT.length + (lo + hi) / 2 - NAME_W / 2)));
+  }
+  return NAME.map((l) => pad + c.amber(l)).join('\n');
+}
+// White hexagon + centred amber wordmark + version. For init, update and the install welcome.
+function logo(c, version) {
+  const art = LOGO.map((l) => INDENT + c.white(l)).join('\n');
+  return `\n${art}\n\n${nameBlock(c, true)}\n\n${INDENT}${c.dim('v' + version + ' · ' + TAGLINE)}\n`;
+}
+// Just the amber wordmark + version. For help and the explore commands.
+function wordmark(c, version) {
+  return `\n${nameBlock(c, false)}\n\n${INDENT}${c.dim('v' + version + ' · ' + TAGLINE)}\n`;
+}
+
+module.exports = { LOGO, NAME, TAGLINE, logo, wordmark };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.16.2",
+  "version": "0.16.4",
   "description": "Agent-agnostic spec-driven development framework + real-time local control plane. Markdown artifacts, intent router, workflow-by-scope.",
   "keywords": [
     "spec-driven-development",
@@ -40,6 +40,7 @@
   ],
   "scripts": {
     "status": "node bin/spectoflow.js status",
+    "postinstall": "node bin/postinstall.js",
     "test": "node --test"
   },
   "engines": {