spyne-cli 0.6.8 → 0.7.1

package/src/cli/render.js

@@ -0,0 +1,198 @@
+// Thin presentation layer. Everything here is terminal chrome — no generation
+// logic lives in this file, and nothing in src/core imports it.
+
+import c from 'ansi-colors';
+import ora from 'ora';
+import {generatePromptOutput} from '../templates/generate-prompt-output.js';
+import {commands} from '../registry.js';
+import {TEMPLATES} from '../core/create-app.js';
+
+/**
+ * Rebuild the legacy shapes generatePromptOutput expects, so module output is
+ * identical to 0.6.8 whether it came from the picker or from flags.
+ */
+export const renderModuleResult = (result) => {
+  const answers = {
+    fileType: result.fileType,
+    fileName: result.fileName,
+    className: result.className,
+    fileDirectory: result.fileDirectory,
+    channelName: result.channelName,
+  };
+  const savedProps = {
+    fileExists: result.error?.code === 'FILE_ALREADY_EXISTS',
+    fileHasSaved: result.ok === true,
+    fileDirPath: result.filePath,
+    errorType: result.errorType,
+  };
+  return generatePromptOutput(answers, savedProps, result.fileString,
+      result.channelRegistered);
+};
+
+export const renderAppResult = (result) => {
+  const lines = [
+    '',
+    c.greenBright('Success!'),
+    `Created ${c.bold(result.appName)} at ${result.path}`,
+    result.generated
+        ? `Template: ${result.template} (AI-generated, app id ${result.appId})`
+        : `Template: ${result.template}`,
+    '',
+    'Next steps:',
+    ...result.nextSteps.map((step) => `  ${c.cyan(step)}`),
+  ];
+  return lines.join('\n');
+};
+
+export const renderError = (error) => `${c.red('Error:')} ${error.message}`;
+
+/**
+ * Enquirer clamps a select's visible rows with Math.min(limit, height), where
+ * height comes from options.rows and falls back to process.stdout.rows. When
+ * that reports 0 — short panes, some CI and multiplexer setups — height wins at
+ * 0 and the list renders as "No matching choices". Passing rows explicitly is
+ * the only way to raise the floor; a real terminal taller than the list keeps
+ * its own value, so this only ever kicks in when the default would break.
+ */
+export const selectSizing = (choiceCount) => {
+  const needed = choiceCount + 2;
+  const limit = choiceCount;
+  return {limit, rows: Math.max(process.stdout.rows || 0, needed)};
+};
+
+/**
+ * Template choices for the enquirer select. `name` must be the template key,
+ * not the label — it is what reaches createApp.
+ */
+export const templateChoices = () => Object.values(TEMPLATES).map((t) => ({
+  name: t.value,
+  message: c.greenBright(t.label),
+  hint: c.dim(`— ${t.description}`),
+}));
+
+export const templatePrompt = () => {
+  const choices = templateChoices();
+  return {
+    type: 'select',
+    name: 'template',
+    message: c.blueBright('Choose a template'),
+    choices,
+    ...selectSizing(choices.length),
+  };
+};
+
+export const appNamePrompt = () => ({
+  type: 'input',
+  name: 'appName',
+  message: c.blueBright('Enter the application name'),
+  initial: 'my-spyne-app',
+  validate: (value) => String(value).trim().length > 0 ||
+      'An app name is required.',
+});
+
+// The default follow-up when the shell template is chosen: describing the
+// site routes scaffolding through the AI generator; Enter on an empty line
+// keeps the blank shell clone.
+export const sitePromptPrompt = () => ({
+  type: 'input',
+  name: 'prompt',
+  message: c.blueBright(
+      'Describe your site — AI generates its pages and content ' +
+      '(Enter to skip for the blank shell)'),
+  initial: '',
+});
+
+export const createProgressReporter = () => {
+  let spinner;
+  return ({status, message}) => {
+    if (status === 'start') {
+      spinner = ora({text: message, spinner: 'dots'}).start();
+      return;
+    }
+    if (!spinner) return;
+    if (status === 'success') spinner.succeed(message);
+    else if (status === 'fail') spinner.fail(message);
+    else spinner.info(message);
+    spinner = undefined;
+  };
+};
+
+const isPositional = (def) => typeof def.positional === 'number';
+
+const describeArg = (def) => {
+  const parts = [def.description];
+  if (def.enum) parts.push(`Values: ${def.enum.join(' | ')}.`);
+  if (def.default !== undefined && def.type !== 'boolean') {
+    parts.push(`Default: ${def.default}.`);
+  }
+  return parts.filter(Boolean).join(' ');
+};
+
+const formatOption = ([name, def]) => {
+  // A boolean that defaults true is only actionable in its --no- form, so that
+  // is what help shows. `description` stays true to the positive form for
+  // programmatic consumers of the registry.
+  const showNegated = def.type === 'boolean' && def.default === true;
+  const flag = showNegated
+      ? `--no-${name}`
+      : (def.alias ? `-${def.alias}, --${name}` : `--${name}`);
+  const description = showNegated
+      ? (def.negatedDescription || `Skip: ${def.description}`)
+      : describeArg(def);
+  return `    ${flag.padEnd(20)} ${description}`;
+};
+
+const formatPositional = ([name, def]) =>
+    `    ${`<${name}>`.padEnd(20)} ${describeArg(def)}`;
+
+export const renderCommandHelp = (command) => {
+  const entries = Object.entries(command.args);
+  const positionals = entries.filter(([, def]) => isPositional(def));
+  const options = entries.filter(([, def]) => !isPositional(def));
+  const usage = [
+    'spyne-cli',
+    command.name,
+    ...positionals.map(([name, def]) => def.required ? `<${name}>` : `[${name}]`),
+    options.length ? '[options]' : '',
+  ].filter(Boolean).join(' ');
+
+  return [
+    '',
+    `  ${c.bold(command.name)} — ${command.summary}`,
+    '',
+    '  Usage:',
+    `    ${usage}`,
+    ...(positionals.length
+        ? ['', '  Arguments:', ...positionals.map(formatPositional)]
+        : []),
+    ...(options.length ? ['', '  Options:', ...options.map(formatOption)] : []),
+    '',
+  ].join('\n');
+};
+
+export const renderHelp = (version) => {
+  const templateList = Object.values(TEMPLATES).
+      map((t) => `    ${t.value.padEnd(12)} ${t.description}`).
+      join('\n');
+
+  return [
+    '',
+    `  spyne-cli ${version}`,
+    '',
+    '  Usage:',
+    '    spyne-cli                      interactive picker',
+    '    spyne-cli <command> [options]',
+    '',
+    '  Commands:',
+    ...commands.map((cmd) => `    ${cmd.name.padEnd(20)} ${cmd.summary}`),
+    '',
+    '  Templates (create-app):',
+    templateList,
+    '',
+    '  Global options:',
+    '    --json                 machine-readable output, human chrome suppressed',
+    '    -h, --help             show help; pass a command name for its options',
+    '    -v, --version          print version',
+    '',
+  ].join('\n');
+};

package/src/core/create-app.js

@@ -0,0 +1,256 @@
+// Core app scaffolding. No terminal output — callers pass an optional
+// onProgress callback and render however they like.
+
+import fs from 'fs';
+import path from 'path';
+import {spawn} from 'child_process';
+import simpleGit from 'simple-git';
+import {fetchGeneratedApp} from './generate-app.js';
+
+// Template keys mirror the distinguishing suffix of their repo names:
+// spynejs/application-starter and spynejs/application-shell.
+export const TEMPLATES = {
+  starter: {
+    value: 'starter',
+    label: 'Application Starter',
+    description: 'minimal: app.js + a hello-world view',
+    repo: 'https://github.com/spynejs/application-starter.git',
+  },
+  shell: {
+    value: 'shell',
+    label: 'Application Shell',
+    description: 'pages, navigation, and UI components built in',
+    repo: 'https://github.com/spynejs/application-shell.git',
+  },
+};
+
+// Accepted silently; only the canonical values are documented.
+const TEMPLATE_ALIASES = {
+  'app-shell': 'shell',
+  'application-shell': 'shell',
+  'application-starter': 'starter',
+};
+
+export const DEFAULT_TEMPLATE = 'starter';
+
+export const resolveTemplate = (name) => {
+  if (!name) return DEFAULT_TEMPLATE;
+  const key = String(name).toLowerCase();
+  return TEMPLATE_ALIASES[key] || key;
+};
+
+/**
+ * Clone URL for a template. An env override lets a fork — or this repo before
+ * the templates are published — scaffold from somewhere else. Read at call
+ * time so it is settable per invocation.
+ *
+ *   SPYNE_CLI_STARTER_REPO, SPYNE_CLI_SHELL_REPO
+ */
+export const repoFor = (templateKey) => {
+  const envKey = `SPYNE_CLI_${templateKey.toUpperCase().replace(/-/g, '_')}_REPO`;
+  return process.env[envKey] || TEMPLATES[templateKey].repo;
+};
+
+export const sanitizePackageName = (appName) => String(appName).
+    toLowerCase().
+    replace(/\s+/g, '-').
+    replace(/[^a-z0-9\-_.]/g, '') || 'my-spyne-app';
+
+const run = (command, args, cwd) => new Promise((resolve) => {
+  const child = spawn(command, args, {cwd, stdio: 'ignore', shell: false});
+  child.on('close', (code) => resolve(code));
+  child.on('error', () => resolve(-1));
+});
+
+const updateIndexTitle = (targetDir, appName) => {
+  const indexFilePath = path.join(targetDir, 'src', 'index.tmpl.html');
+  if (!fs.existsSync(indexFilePath)) return;
+  const content = fs.readFileSync(indexFilePath, 'utf-8');
+  fs.writeFileSync(indexFilePath,
+      content.replace(/<title>.*<\/title>/, `<title>${appName}</title>`),
+      'utf-8');
+};
+
+const updatePackageName = (targetDir, appName) => {
+  const pkgPath = path.join(targetDir, 'package.json');
+  if (!fs.existsSync(pkgPath)) return;
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  pkg.name = sanitizePackageName(appName);
+  pkg.version = '0.1.0';
+  delete pkg.repository;
+  delete pkg.homepage;
+  fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf-8');
+};
+
+/**
+ * Rebrand a freshly cloned template as the user's app. Exported so the
+ * post-clone pipeline is testable without reaching the network.
+ */
+export const applyProjectIdentity = (targetDir, appName) => {
+  updateIndexTitle(targetDir, appName);
+  updatePackageName(targetDir, appName);
+};
+
+/**
+ * Detect whether cwd (or an ancestor) looks like a SpyneJS project.
+ * Used to guard `create-app` inside a project and module generation outside one.
+ */
+export const detectSpyneProject = (startDir = process.cwd()) => {
+  let dir = path.resolve(startDir);
+  while (true) {
+    const pkgPath = path.join(dir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        const deps = {...pkg.dependencies, ...pkg.devDependencies};
+        if (deps && deps.spyne) return {isSpyneProject: true, root: dir};
+      } catch {
+        // unreadable package.json — keep walking up
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return {isSpyneProject: false, root: null};
+    dir = parent;
+  }
+};
+
+/**
+ * Create a new SpyneJS application.
+ *
+ * @param {Object} args
+ * @param {string} args.appName
+ * @param {string} [args.template] 'starter' | 'shell'
+ * @param {boolean} [args.install] install dependencies (default true)
+ * @param {boolean} [args.git] initialise a fresh git repo (default true)
+ * @param {Function} [args.onProgress] ({step, status, message}) => void
+ * @returns {Promise<Object>} structured result
+ */
+export async function createApp(args = {}) {
+  const {appName, onProgress = () => {}} = args;
+  const install = args.install !== false;
+  const initGit = args.git !== false;
+
+  if (!appName) {
+    return {
+      ok: false,
+      error: {code: 'MISSING_APP_NAME', message: 'An app name is required.'},
+    };
+  }
+
+  const templateKey = resolveTemplate(args.template);
+  const template = TEMPLATES[templateKey];
+
+  if (!template) {
+    return {
+      ok: false,
+      error: {
+        code: 'UNKNOWN_TEMPLATE',
+        message: `Unknown template "${args.template}". Expected one of: ${Object.keys(
+            TEMPLATES).join(', ')}.`,
+      },
+    };
+  }
+
+  const targetDir = path.resolve(process.cwd(), appName);
+
+  if (fs.existsSync(targetDir)) {
+    return {
+      ok: false,
+      error: {
+        code: 'DIRECTORY_EXISTS',
+        message: `${targetDir} already exists.`,
+      },
+      path: targetDir,
+    };
+  }
+
+  // A site description routes the shell template through the AI generator
+  // instead of a plain clone; everything after acquisition is shared.
+  const sitePrompt = args.prompt && String(args.prompt).trim();
+  if (sitePrompt && templateKey !== 'shell') {
+    return {
+      ok: false,
+      error: {
+        code: 'PROMPT_UNSUPPORTED',
+        message: 'A site description generates from the shell template. ' +
+            'Use --template shell (or drop --prompt).',
+      },
+    };
+  }
+
+  const repo = repoFor(templateKey);
+  let generated;
+
+  if (sitePrompt) {
+    generated = await fetchGeneratedApp({sitePrompt, targetDir, onProgress});
+    if (!generated.ok) return generated;
+  } else {
+    onProgress({step: 'clone', status: 'start', message: 'Cloning template...'});
+    try {
+      await simpleGit().clone(repo, targetDir,
+          ['--branch=main', '--single-branch', '--depth=1']);
+      onProgress({step: 'clone', status: 'success', message: 'Template cloned.'});
+    } catch (err) {
+      onProgress({step: 'clone', status: 'fail', message: 'Clone failed.'});
+      return {
+        ok: false,
+        error: {
+          code: 'CLONE_FAILED',
+          message: `Could not clone ${repo}: ${err.message}`,
+        },
+      };
+    }
+
+    // No .git leakage from the template repo.
+    fs.rmSync(path.join(targetDir, '.git'), {recursive: true, force: true});
+  }
+
+  applyProjectIdentity(targetDir, appName);
+
+  let gitInitialized = false;
+  if (initGit) {
+    onProgress({step: 'git', status: 'start', message: 'Initialising git...'});
+    gitInitialized = await run('git', ['init', '--quiet'], targetDir) === 0;
+    onProgress({
+      step: 'git',
+      status: gitInitialized ? 'success' : 'skip',
+      message: gitInitialized ? 'Git repository initialised.' : 'Skipped git init.',
+    });
+  }
+
+  let dependenciesInstalled = false;
+  if (install) {
+    onProgress({
+      step: 'install',
+      status: 'start',
+      message: 'Installing dependencies...',
+    });
+    dependenciesInstalled =
+        await run('npm', ['install', '--silent'], targetDir) === 0;
+    onProgress({
+      step: 'install',
+      status: dependenciesInstalled ? 'success' : 'fail',
+      message: dependenciesInstalled
+          ? 'Dependencies installed.'
+          : 'Dependency install failed — run npm install manually.',
+    });
+  }
+
+  return {
+    ok: true,
+    appName,
+    path: targetDir,
+    template: templateKey,
+    ...(generated
+        ? {generated: true, appId: generated.appId}
+        : {templateRepo: repo}),
+    gitInitialized,
+    dependenciesInstalled,
+    nextSteps: [
+      `cd ${appName}`,
+      ...(dependenciesInstalled ? [] : ['npm install']),
+      'npm start',
+      ...(generated ? ['see GETTING-STARTED.md for the CMS claim + AI editing'] : []),
+    ],
+  };
+}

package/src/core/generate-app.js

@@ -0,0 +1,155 @@
+// AI-generated app scaffolding: the shell template, but with pages, routes,
+// content, and images produced by the SpyneJS generator service from one
+// site description. Same contract as the clone path — no terminal output,
+// progress via callback, structured result.
+
+import fs from 'fs';
+import path from 'path';
+import {unzipSync} from 'fflate';
+
+/**
+ * Endpoint for the generator service (POST /generate). Env override mirrors
+ * the template-repo override pattern; read at call time.
+ */
+export const DEFAULT_GENERATOR_URL =
+    'https://ntvylgarzwinj3lcwtyctwlclu0ldpjp.lambda-url.us-east-1.on.aws/';
+
+export const generatorUrl = () =>
+    process.env.SPYNE_CLI_GENERATOR_URL || DEFAULT_GENERATOR_URL;
+
+const errorFor = (status, body) => {
+  if (status === 422) {
+    return {
+      code: 'GENERATION_INVALID',
+      message: 'The generator could not produce a valid site from that ' +
+          'description. Try rephrasing it.',
+    };
+  }
+  if (status === 429) {
+    return {
+      code: 'RATE_LIMITED',
+      message: 'The anonymous generation quota for this network was reached. ' +
+          'Try again later.',
+    };
+  }
+  if (status === 503 || status === 504) {
+    return {
+      code: 'GENERATION_TIMEOUT',
+      message: 'The generator took too long to respond. Try again — complex ' +
+          'descriptions occasionally need a second attempt.',
+    };
+  }
+  return {
+    code: 'GENERATION_FAILED',
+    message: `Generator request failed (${status}): ` +
+        `${(body && body.error) || 'unexpected response'}.`,
+  };
+};
+
+/**
+ * Extract a generated package zip into targetDir, stripping the single
+ * top-level directory the package wraps its files in. Entries that would
+ * escape targetDir are rejected.
+ */
+export const extractPackage = (zipBuffer, targetDir) => {
+  const entries = unzipSync(new Uint8Array(zipBuffer));
+  const resolvedTarget = path.resolve(targetDir);
+
+  for (const [entryPath, data] of Object.entries(entries)) {
+    if (entryPath.endsWith('/')) continue;
+    const stripped = entryPath.split('/').slice(1).join('/');
+    if (!stripped) continue;
+    const dest = path.resolve(resolvedTarget, stripped);
+    if (!dest.startsWith(resolvedTarget + path.sep)) {
+      throw new Error(`Unsafe path in package: ${entryPath}`);
+    }
+    fs.mkdirSync(path.dirname(dest), {recursive: true});
+    fs.writeFileSync(dest, data);
+  }
+};
+
+/**
+ * Generate an application from a site description. Called by createApp once
+ * appName/targetDir are validated; performs the network stages and extraction,
+ * leaving identity, git, and install to the shared pipeline.
+ *
+ * @returns {Promise<Object>} {ok, ...} — on success includes appId and
+ *     claimToken so renderers can surface the CMS claim.
+ */
+export async function fetchGeneratedApp({sitePrompt, targetDir, onProgress}) {
+  onProgress({
+    step: 'generate',
+    status: 'start',
+    message: 'Generating site with AI (this can take up to a minute)...',
+  });
+
+  let res;
+  let body;
+  try {
+    res = await fetch(generatorUrl(), {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({prompt: sitePrompt}),
+      signal: AbortSignal.timeout(120000),
+    });
+    body = await res.json().catch(() => ({}));
+  } catch (err) {
+    onProgress({step: 'generate', status: 'fail', message: 'Generation failed.'});
+    return {
+      ok: false,
+      error: {
+        code: 'GENERATION_UNREACHABLE',
+        message: `Could not reach the generator: ${err.message}`,
+      },
+    };
+  }
+
+  if (!res.ok || !body.packageUrl) {
+    onProgress({step: 'generate', status: 'fail', message: 'Generation failed.'});
+    return {ok: false, error: errorFor(res.status, body)};
+  }
+
+  const pageCount = Array.isArray(body.appModel && body.appModel.content)
+      ? body.appModel.content.length
+      : undefined;
+  onProgress({
+    step: 'generate',
+    status: 'success',
+    message: pageCount
+        ? `Site generated (${pageCount} pages).`
+        : 'Site generated.',
+  });
+
+  onProgress({step: 'download', status: 'start', message: 'Downloading package...'});
+  let zipBuffer;
+  try {
+    const zipRes = await fetch(body.packageUrl,
+        {signal: AbortSignal.timeout(120000)});
+    if (!zipRes.ok) throw new Error(`HTTP ${zipRes.status}`);
+    zipBuffer = Buffer.from(await zipRes.arrayBuffer());
+  } catch (err) {
+    onProgress({step: 'download', status: 'fail', message: 'Download failed.'});
+    return {
+      ok: false,
+      error: {
+        code: 'DOWNLOAD_FAILED',
+        message: `Could not download the package: ${err.message}`,
+      },
+    };
+  }
+  onProgress({step: 'download', status: 'success', message: 'Package downloaded.'});
+
+  try {
+    extractPackage(zipBuffer, targetDir);
+  } catch (err) {
+    return {
+      ok: false,
+      error: {
+        code: 'EXTRACT_FAILED',
+        message: `Could not extract the package: ${err.message}`,
+      },
+    };
+  }
+
+  return {ok: true, appId: body.appId, claimToken: body.claimToken};
+}